@jet-w/astro-blog 0.1.5 → 0.2.0

package/templates/default/content/posts/blog_docs_en/get-started/02-install.md

@@ -0,0 +1,137 @@
+---
+title: Installation
+description: Set up your development environment and install Astro Blog
+pubDate: 2025-01-01
+author: Astro Blog
+categories:
+  - Documentation
+tags:
+  - Getting Started
+  - Installation
+---
+
+# Installation
+
+This guide will help you set up Astro Blog on your computer.
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+### Node.js
+
+Node.js 18.x or higher is required.
+
+```bash
+# Check your Node.js version
+node --version
+# Should output: v18.x.x or higher
+```
+
+::: tip Installing Node.js
+If you don't have Node.js, download it from [nodejs.org](https://nodejs.org).
+Choose the **LTS** version for the best stability.
+:::
+
+### Package Manager
+
+npm comes with Node.js. You can also use pnpm or yarn:
+
+```bash
+# Check npm version
+npm --version
+
+# Or use pnpm (recommended for faster installs)
+npm install -g pnpm
+pnpm --version
+```
+
+## Install Dependencies
+
+Navigate to your blog project folder and install dependencies:
+
+```bash
+# Using npm
+npm install
+
+# Or using pnpm
+pnpm install
+```
+
+This will install all required packages defined in `package.json`.
+
+## Start Development Server
+
+Start the local development server:
+
+```bash
+# Using npm
+npm run dev
+
+# Or using pnpm
+pnpm dev
+```
+
+You should see output like:
+
+```
+🚀 astro  v5.x.x ready in 1234ms
+
+┃ Local    http://localhost:4321/
+┃ Network  use --host to expose
+```
+
+::: tip Hot Reload
+The development server supports hot reload. When you save a file, the browser automatically refreshes to show your changes.
+:::
+
+## Open in Browser
+
+Visit `http://localhost:4321` in your browser. You should see your blog's homepage!
+
+## Verify Installation
+
+Check that everything works:
+
+1. **Homepage loads** - You see the blog homepage
+2. **Posts list** - Navigate to `/posts` to see articles
+3. **Dark mode** - Toggle the theme switch in the header
+4. **Search** - Try the search function
+
+## Common Issues
+
+### Port Already in Use
+
+If port 4321 is busy, Astro will use another port. Check the terminal output for the actual URL.
+
+Or specify a different port:
+
+```bash
+npm run dev -- --port 3000
+```
+
+### Dependencies Not Installing
+
+Try clearing the cache:
+
+```bash
+# Remove node_modules and lock file
+rm -rf node_modules package-lock.json
+
+# Reinstall
+npm install
+```
+
+### Node.js Version Too Old
+
+Update Node.js to version 18 or higher. Consider using [nvm](https://github.com/nvm-sh/nvm) to manage Node versions:
+
+```bash
+# Install nvm, then:
+nvm install 20
+nvm use 20
+```
+
+---
+
+Development server running? Great! Let's [create your first post](./03-create-post).

package/templates/default/content/posts/blog_docs_en/get-started/03-create-post.md

@@ -0,0 +1,176 @@
+---
+title: Create Your First Post
+description: Write and publish your first blog article
+pubDate: 2025-01-01
+author: Astro Blog
+categories:
+  - Documentation
+tags:
+  - Getting Started
+  - Writing
+---
+
+# Create Your First Post
+
+Let's write your first blog post! This is where the fun begins.
+
+## Where Posts Live
+
+All blog posts go in the `content/posts/` directory:
+
+```
+content/
+└── posts/
+    ├── my-first-post.md    ← Your posts go here
+    ├── another-post.md
+    └── tech/               ← Or in subdirectories
+        └── tutorial.md
+```
+
+## Create a New Post
+
+Create a file called `hello-world.md` in `content/posts/`:
+
+```markdown
+---
+title: Hello World
+description: My first blog post
+pubDate: 2025-01-15
+author: Your Name
+tags:
+  - Introduction
+categories:
+  - Personal
+---
+
+# Hello World
+
+Welcome to my blog! This is my first post.
+
+## Why I Started Blogging
+
+I started this blog to:
+
+1. Share what I learn
+2. Document my journey
+3. Connect with others
+
+> The best time to start was yesterday. The second best time is now.
+
+## What's Next
+
+Stay tuned for more posts about:
+
+- Web development
+- My projects
+- Lessons learned
+
+Thanks for reading!
+```
+
+## View Your Post
+
+Save the file and visit:
+
+```
+http://localhost:4321/posts/hello-world
+```
+
+Your post should appear with full styling!
+
+## Understanding Frontmatter
+
+The section between `---` markers is called **frontmatter**. It contains metadata about your post:
+
+```yaml
+---
+title: Hello World          # Required - Post title
+description: My first post  # For SEO and previews
+pubDate: 2025-01-15        # Publication date
+author: Your Name          # Author name
+tags:                      # Tags (array)
+  - Introduction
+categories:                # Categories (array)
+  - Personal
+draft: false               # true = hidden from listing
+star: false                # true = featured post
+---
+```
+
+::: tip Required vs Optional
+Only `title` is required. All other fields are optional but recommended for better organization and SEO.
+:::
+
+## Using Subdirectories
+
+Organize related posts in subdirectories:
+
+```
+content/posts/
+├── tutorials/
+│   ├── README.md        ← Shows at /posts/tutorials
+│   ├── javascript.md    ← Shows at /posts/tutorials/javascript
+│   └── css.md           ← Shows at /posts/tutorials/css
+└── projects/
+    └── my-app.md        ← Shows at /posts/projects/my-app
+```
+
+### Directory README
+
+Each directory can have a `README.md` that serves as the directory's index page:
+
+```markdown
+---
+title: Tutorials
+description: Learn web development step by step
+---
+
+# Tutorials
+
+Welcome to my tutorials section!
+
+- [JavaScript Basics](./javascript)
+- [CSS Tricks](./css)
+```
+
+## URL Path Rules
+
+Your file path determines the URL:
+
+| File Path | URL |
+|-----------|-----|
+| `posts/hello.md` | `/posts/hello` |
+| `posts/tech/intro.md` | `/posts/tech/intro` |
+| `posts/tech/README.md` | `/posts/tech` |
+
+::: info Case Insensitive
+URLs are automatically lowercased. `Hello-World.md` becomes `/posts/hello-world`.
+:::
+
+## Adding Images
+
+Place images in `public/images/` and reference them:
+
+```markdown
+![My Photo](/images/photo.jpg)
+```
+
+For post-specific images, you can create a folder:
+
+```
+public/
+└── images/
+    └── posts/
+        └── hello-world/
+            └── cover.jpg
+```
+
+Then use:
+
+```markdown
+![Cover](/images/posts/hello-world/cover.jpg)
+```
+
+---
+
+Congratulations on your first post! Next, let's understand the [project structure](./04-structure).

package/templates/default/content/posts/blog_docs_en/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: Astro Blog
+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/get-started/05-deploy.md

@@ -0,0 +1,197 @@
+---
+title: Deployment
+description: Build and deploy your blog to the web
+pubDate: 2025-01-01
+author: Astro Blog
+categories:
+  - Documentation
+tags:
+  - Getting Started
+  - Deployment
+---
+
+# Deployment
+
+Time to share your blog with the world! Let's build and deploy.
+
+## 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.
+
+## Deployment Options
+
+Your static site can be hosted anywhere. Here are popular options:
+
+### Vercel (Recommended)
+
+::: tip Why Vercel?
+- **Zero configuration** - Automatic Astro detection
+- **Free tier** - Generous free hosting
+- **Fast** - Global CDN
+:::
+
+1. Push your code to GitHub
+2. Visit [vercel.com](https://vercel.com)
+3. Import your repository
+4. Click Deploy
+
+Vercel automatically:
+- Detects Astro
+- Runs `npm run build`
+- Deploys the `dist/` folder
+
+### Netlify
+
+1. Push code to GitHub
+2. Visit [netlify.com](https://netlify.com)
+3. Connect your repository
+4. Set build settings:
+   - Build command: `npm run build`
+   - Publish directory: `dist`
+
+### GitHub Pages
+
+1. Add to `astro.config.mjs`:
+
+```javascript
+export default defineConfig({
+  site: 'https://username.github.io',
+  base: '/repo-name/',  // If not using custom domain
+});
+```
+
+2. Create `.github/workflows/deploy.yml`:
+
+```yaml
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install
+      - run: npm run build
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/deploy-pages@v4
+        id: deployment
+```
+
+3. Enable GitHub Pages in repository settings
+
+### Cloudflare Pages
+
+1. Connect repository at [pages.cloudflare.com](https://pages.cloudflare.com)
+2. Set build settings:
+   - Framework preset: Astro
+   - Build command: `npm run build`
+   - Output directory: `dist`
+
+## Environment Variables
+
+For sensitive data, use environment variables:
+
+```bash
+# .env (local development)
+PUBLIC_SITE_URL=https://myblog.com
+```
+
+Access in code:
+
+```javascript
+const siteUrl = import.meta.env.PUBLIC_SITE_URL;
+```
+
+::: warning Public vs Private
+Variables prefixed with `PUBLIC_` are exposed to the browser.
+Keep API keys and secrets without the `PUBLIC_` prefix.
+:::
+
+## Custom Domain
+
+Most platforms support custom domains:
+
+1. **Buy a domain** (Namecheap, Google Domains, etc.)
+2. **Add to platform** - Follow platform-specific instructions
+3. **Update DNS** - Point to platform's servers
+4. **SSL** - Usually automatic (free with Let's Encrypt)
+
+## 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
+
+With GitHub + Vercel/Netlify:
+
+1. Push changes to `main` branch
+2. Platform automatically rebuilds
+3. Site updates in ~1 minute
+
+```bash
+git add .
+git commit -m "Add new blog post"
+git push origin main
+# Site automatically updates!
+```
+
+---
+
+Congratulations! You've completed the Get Started guide.
+
+Continue learning with the [Writing Guide](../guide/) to master content creation.