@jet-w/astro-blog 0.1.6 → 0.2.1

package/templates/default/content/posts/blog_docs_en/01.get-started/04-structure.md

@@ -0,0 +1,173 @@
+---
+title: Project Structure
+description: Understand how files and folders are organized
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - Documentation
+tags:
+  - Getting Started
+  - Structure
+---
+
+# Project Structure
+
+Understanding the project structure helps you know where to find and place files.
+
+## Overview
+
+```
+your-blog/
+├── content/              # Your content
+│   ├── posts/           # Blog posts
+│   └── pages/           # Standalone pages
+├── public/               # Static assets
+│   ├── images/          # Images
+│   └── videos/          # Videos
+├── src/
+│   ├── config/          # Configuration files
+│   │   ├── locales/     # Language configs
+│   │   ├── site.ts      # Site settings
+│   │   └── ...
+│   └── ...
+├── astro.config.mjs      # Astro configuration
+└── package.json          # Dependencies
+```
+
+## Content Directory
+
+This is where your content lives:
+
+### posts/
+
+Blog posts in Markdown or MDX format:
+
+```
+content/posts/
+├── hello-world.md         # Individual post
+├── tutorials/             # Category folder
+│   ├── README.md         # Category index
+│   └── getting-started.md
+└── blog_docs_en/          # Documentation
+    └── ...
+```
+
+### pages/
+
+Standalone pages like About, Contact:
+
+```
+content/pages/
+├── about.md              # /about
+└── contact.md            # /contact
+```
+
+## Public Directory
+
+Static files served directly:
+
+```
+public/
+├── images/               # Images
+│   ├── avatar.jpg       # /images/avatar.jpg
+│   └── posts/           # Post images
+├── videos/               # Videos
+├── favicon.svg           # Site favicon
+└── robots.txt           # SEO file
+```
+
+::: tip Direct Access
+Files in `public/` are served at the root URL.
+`public/images/cat.jpg` → `https://yoursite.com/images/cat.jpg`
+:::
+
+## Configuration Directory
+
+Site configuration files:
+
+```
+src/config/
+├── locales/              # Language-specific configs
+│   ├── en/              # English
+│   │   ├── index.ts
+│   │   ├── site.ts
+│   │   ├── menu.ts
+│   │   ├── footer.ts
+│   │   └── sidebar.ts
+│   └── zh-CN/           # Chinese
+│       └── ...
+├── site.ts               # Default site config
+├── menu.ts               # Default menu
+├── sidebar.ts            # Sidebar settings
+├── footer.ts             # Footer settings
+└── social.ts             # Social links
+```
+
+## Key Configuration Files
+
+### astro.config.mjs
+
+Main Astro configuration:
+
+```javascript
+export default defineConfig({
+  integrations: [
+    astroBlog({ i18n: i18nConfig }),
+    vue(),
+    tailwind(),
+  ],
+  site: 'https://yourdomain.com',
+});
+```
+
+### src/config/site.ts
+
+Site metadata:
+
+```typescript
+export const siteConfig = {
+  title: 'My Blog',
+  description: 'A blog about...',
+  author: 'Your Name',
+  avatar: '/images/avatar.jpg',
+};
+```
+
+### src/config/menu.ts
+
+Navigation links:
+
+```typescript
+export const menu = [
+  { name: 'Home', href: '/', icon: 'home' },
+  { name: 'Posts', href: '/posts', icon: 'posts' },
+  { name: 'About', href: '/about', icon: 'about' },
+];
+```
+
+## File Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Posts | lowercase with dashes | `my-first-post.md` |
+| Config | camelCase or kebab | `site.ts`, `menu.ts` |
+| Images | descriptive names | `hero-banner.jpg` |
+
+::: warning Avoid Spaces
+Don't use spaces in filenames. Use dashes instead:
+- ❌ `my first post.md`
+- ✅ `my-first-post.md`
+:::
+
+## What Each Folder Does
+
+| Folder | Purpose | You Should... |
+|--------|---------|---------------|
+| `content/posts/` | Blog posts | Add your articles here |
+| `content/pages/` | Static pages | Add about, contact pages |
+| `public/` | Static assets | Put images, files |
+| `src/config/` | Settings | Customize your site |
+
+---
+
+Now you understand the structure! Let's learn how to [deploy your blog](./05-deploy).

package/templates/default/content/posts/blog_docs_en/01.get-started/05-deploy.md

@@ -0,0 +1,208 @@
+---
+title: Deployment
+description: Build and deploy your blog to GitHub Pages
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - Documentation
+tags:
+  - Getting Started
+  - Deployment
+---
+
+# Deployment
+
+Time to share your blog with the world! This guide covers deploying to GitHub Pages.
+
+## Build for Production
+
+First, create a production build:
+
+```bash
+npm run build
+```
+
+This creates a `dist/` folder with static files:
+
+```
+dist/
+├── index.html
+├── posts/
+│   └── hello-world/
+│       └── index.html
+├── assets/
+│   ├── styles.css
+│   └── scripts.js
+└── ...
+```
+
+## Preview Locally
+
+Test the build before deploying:
+
+```bash
+npm run preview
+```
+
+Visit `http://localhost:4321` to verify everything works.
+
+## Deploy to GitHub Pages
+
+### Step 1: Configure Astro
+
+Update your `astro.config.mjs`:
+
+```javascript
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  site: 'https://username.github.io',
+  base: '/repo-name/',  // Only if NOT using custom domain
+});
+```
+
+::: tip Custom Domain
+If using a custom domain (e.g., `myblog.com`), set `base: '/'` or remove it entirely.
+:::
+
+### Step 2: Create GitHub Actions Workflow
+
+Create `.github/workflows/deploy.yml`:
+
+```yaml
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+### Step 3: Enable GitHub Pages
+
+1. Go to your repository on GitHub
+2. Navigate to **Settings** → **Pages**
+3. Under "Build and deployment", select **GitHub Actions** as the source
+4. Push your code to the `main` branch
+
+Your site will be available at `https://username.github.io/repo-name/`
+
+### Step 4: Custom Domain (Optional)
+
+To use a custom domain:
+
+1. **Add CNAME file**: Create `public/CNAME` with your domain:
+   ```
+   myblog.com
+   ```
+
+2. **Configure DNS**: Add these records at your domain registrar:
+   - **A records** (for apex domain like `myblog.com`):
+     ```
+     185.199.108.153
+     185.199.109.153
+     185.199.110.153
+     185.199.111.153
+     ```
+   - **CNAME record** (for `www` subdomain):
+     ```
+     www -> username.github.io
+     ```
+
+3. **Update Astro config**:
+   ```javascript
+   export default defineConfig({
+     site: 'https://myblog.com',
+     // No base needed for custom domain
+   });
+   ```
+
+4. **Enable in GitHub**: In repository Settings → Pages, add your custom domain
+
+::: info SSL Certificate
+GitHub automatically provisions a free SSL certificate. It may take up to 24 hours.
+:::
+
+## Deployment Checklist
+
+Before deploying, verify:
+
+- [ ] `npm run build` completes without errors
+- [ ] `npm run preview` shows site correctly
+- [ ] All links work (no broken links)
+- [ ] Images load properly
+- [ ] Meta tags are set (title, description)
+- [ ] Favicon is configured
+
+## Continuous Deployment
+
+Once configured, your site updates automatically:
+
+```bash
+git add .
+git commit -m "Add new blog post"
+git push origin main
+# Site automatically updates in ~1-2 minutes!
+```
+
+## Other Deployment Options
+
+This blog can be deployed to any static hosting platform:
+
+- **Vercel** - Zero-config Astro support, global CDN
+- **Netlify** - Easy setup with form handling
+- **Cloudflare Pages** - Fast edge network, free tier
+- **AWS S3 + CloudFront** - Scalable cloud hosting
+- **Firebase Hosting** - Google's hosting platform
+
+For detailed instructions on these platforms, refer to the [Astro Deployment Guides](https://docs.astro.build/en/guides/deploy/).
+
+---
+
+Congratulations! You've completed the Get Started guide.
+
+Continue learning with the [Writing Guide](/posts/blog_docs_en/02.guide) to master content creation.

package/templates/default/content/posts/blog_docs_en/01.get-started/README.md

@@ -0,0 +1,52 @@
+---
+title: Get Started
+description: Begin your journey with Astro Blog - from installation to deployment
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - Documentation
+tags:
+  - Getting Started
+  - Tutorial
+---
+
+# Get Started
+
+Welcome! This guide will walk you through setting up your Astro Blog from scratch.
+
+::: tip Who Is This For?
+This tutorial is designed for beginners. Even if you're new to Astro or static site generators, you'll be able to follow along step by step.
+:::
+
+## Learning Path
+
+Follow these chapters in order:
+
+| Step | Chapter | What You'll Learn |
+|------|---------|-------------------|
+| 1 | [Introduction](./01-intro) | What Astro Blog is and its features |
+| 2 | [Installation](./02-install) | Set up Node.js and install the project |
+| 3 | [First Post](./03-create-post) | Write and publish your first article |
+| 4 | [Project Structure](./04-structure) | Understand how files are organized |
+| 5 | [Deployment](./05-deploy) | Build and deploy to the web |
+
+## Prerequisites
+
+Before starting, make sure you have:
+
+- **Node.js 18+** installed on your computer
+- A **code editor** (VS Code recommended)
+- Basic familiarity with the **command line**
+
+::: info Don't Have Node.js?
+Download it from [nodejs.org](https://nodejs.org). Choose the LTS (Long Term Support) version.
+:::
+
+## Time Required
+
+- **Quick setup**: ~5 minutes
+- **Full tutorial**: ~30 minutes
+
+---
+
+Ready? Let's start with the [Introduction](./01-intro)!

package/templates/default/content/posts/blog_docs_en/02.guide/02-containers.md

@@ -0,0 +1,245 @@
+---
+title: Containers
+description: Use callout boxes for tips, warnings, and important information
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - Documentation
+tags:
+  - Markdown
+  - Containers
+---
+
+# Containers
+
+Containers are special callout boxes that help highlight important information.
+
+## Basic Syntax
+
+```markdown
+::: type
+Content goes here
+:::
+```
+
+## Container Types
+
+### Tip
+
+For helpful suggestions:
+
+```markdown
+::: tip
+This is a helpful tip for the reader.
+:::
+```
+
+<div class="container-tip custom-container" data-container-type="tip">
+<div class="container-title">Tip</div>
+<div class="container-content">
+<p>This is a helpful tip for the reader.</p>
+</div>
+</div>
+
+### Info
+
+For informational notes:
+
+```markdown
+::: info
+Here's some additional information.
+:::
+```
+
+<div class="container-info custom-container" data-container-type="info">
+<div class="container-title">Info</div>
+<div class="container-content">
+<p>Here's some additional information.</p>
+</div>
+</div>
+
+### Warning
+
+For things to be careful about:
+
+```markdown
+::: warning
+Be careful with this operation.
+:::
+```
+
+<div class="container-warning custom-container" data-container-type="warning">
+<div class="container-title">Warning</div>
+<div class="container-content">
+<p>Be careful with this operation.</p>
+</div>
+</div>
+
+### Danger
+
+For critical warnings:
+
+```markdown
+::: danger
+This action cannot be undone!
+:::
+```
+
+<div class="container-danger custom-container" data-container-type="danger">
+<div class="container-title">Danger</div>
+<div class="container-content">
+<p>This action cannot be undone!</p>
+</div>
+</div>
+
+### Note
+
+For general notes:
+
+```markdown
+::: note
+A side note for the reader.
+:::
+```
+
+<div class="container-note custom-container" data-container-type="note">
+<div class="container-title">Note</div>
+<div class="container-content">
+<p>A side note for the reader.</p>
+</div>
+</div>
+
+## Custom Titles
+
+Add a custom title after the type:
+
+```markdown
+::: tip Pro Tip
+This container has a custom title.
+:::
+```
+
+<div class="container-tip custom-container" data-container-type="tip">
+<div class="container-title">Pro Tip</div>
+<div class="container-content">
+<p>This container has a custom title.</p>
+</div>
+</div>
+
+```markdown
+::: warning Security Notice
+Always validate user input!
+:::
+```
+
+<div class="container-warning custom-container" data-container-type="warning">
+<div class="container-title">Security Notice</div>
+<div class="container-content">
+<p>Always validate user input!</p>
+</div>
+</div>
+
+## Rich Content
+
+Containers support full Markdown inside:
+
+```markdown
+::: info Features
+This blog supports:
+- **Markdown** formatting
+- `Code` snippets
+- [Links](https://example.com)
+:::
+```
+
+<div class="container-info custom-container" data-container-type="info">
+<div class="container-title">Features</div>
+<div class="container-content">
+<p>This blog supports:</p>
+<ul>
+<li><strong>Markdown</strong> formatting</li>
+<li><code>Code</code> snippets</li>
+<li><a href="https://example.com">Links</a></li>
+</ul>
+</div>
+</div>
+
+## Details (Collapsible)
+
+Create expandable sections:
+
+```markdown
+::: details Click to expand
+This content is hidden by default.
+You can put lots of content here.
+:::
+```
+
+<details class="container-details custom-container" data-container-type="details">
+<summary class="container-title">Click to expand</summary>
+<div class="container-content">
+<p>This content is hidden by default.</p>
+<p>You can put lots of content here.</p>
+</div>
+</details>
+
+### Details with Code
+
+```markdown
+::: details View the solution
+function solve() {
+  return 42;
+}
+:::
+```
+
+<details class="container-details custom-container" data-container-type="details">
+<summary class="container-title">View the solution</summary>
+<div class="container-content">
+
+```javascript
+function solve() {
+  return 42;
+}
+```
+
+</div>
+</details>
+
+## Best Practices
+
+<div class="container-tip custom-container" data-container-type="tip">
+<div class="container-title">When to Use Containers</div>
+<div class="container-content">
+<ul>
+<li><strong>tip</strong> - Helpful suggestions, best practices</li>
+<li><strong>info</strong> - Background information, context</li>
+<li><strong>warning</strong> - Potential issues, things to watch</li>
+<li><strong>danger</strong> - Critical errors, data loss risks</li>
+<li><strong>note</strong> - General observations</li>
+<li><strong>details</strong> - Optional content, long examples</li>
+</ul>
+</div>
+</div>
+
+<div class="container-warning custom-container" data-container-type="warning">
+<div class="container-title">Don't Overuse</div>
+<div class="container-content">
+<p>Too many containers can be distracting. Use them sparingly for truly important information.</p>
+</div>
+</div>
+
+## Quick Reference
+
+| Type | Syntax | Use Case |
+|------|--------|----------|
+| tip | `::: tip` | Helpful suggestions |
+| info | `::: info` | Additional information |
+| warning | `::: warning` | Cautions |
+| danger | `::: danger` | Critical warnings |
+| note | `::: note` | Side notes |
+| details | `::: details` | Collapsible content |
+
+---
+
+Next: Master [Code Blocks](./03-code-blocks) for beautiful code snippets.