# Astro Blog Tutorial From scratch, create your technical blog
## Table of Contents 1. **System Overview** - Understand blog architecture 2. **Quick Start** - Installation and running 3. **Content Creation** - Article writing guide 4. **Featured Functions** - Markdown enhancements 5. **Slides** - Create presentations 6. **Configuration** - Personalization settings 7. **Deployment** - Publish to the internet
# Chapter 1 ## System Overview
## Tech Stack | Technology | Purpose | |------|------| | **Astro 5** | Static site generator | | **Vue 3** | Interactive components | | **TypeScript** | Type safety | | **Tailwind CSS** | Styling system | | **Reveal.js** | Slide presentations |
## Main Features <p class="fragment">Markdown & MDX support</p> <p class="fragment">Code highlighting (100+ languages)</p> <p class="fragment">Mathematical formulas (LaTeX/KaTeX)</p> <p class="fragment">Flowcharts (Mermaid)</p> <p class="fragment">Data visualization (ECharts)</p> <p class="fragment">Slide presentations (Reveal.js)</p>
## Directory Structure ``` blog/ ├── content/ # Content directory │ ├── posts/ # Blog posts │ ├── pages/ # Static pages │ └── slides/ # Independent slides ├── src/ │ ├── config/ # Configuration files │ ├── components/ # Components │ ├── layouts/ # Layout templates │ └── plugins/ # Markdown plugins └── public/ # Static assets ```
# Chapter 2 ## Quick Start
## Environment Requirements - **Node.js** 18.0 or higher - **npm** or **pnpm** package manager - Code editor (VS Code recommended)
## Installation Steps ```bash # 1. Clone project git clone <repository-url> # 2. Enter directory cd astro-blog # 3. Install dependencies npm install # 4. Start development server npm run dev ```
## Common Commands | Command | Description | |------|------| | `npm run dev` | Start development server | | `npm run build` | Build production version | | `npm run preview` | Preview build results | Visit `http://localhost:4321` to view the blog
# Chapter 3 ## Content Creation
## Creating Articles Create `.md` files in the `content/posts/` directory: ``` content/posts/ ├── my-first-post.md # Root directory article ├── tutorial/ │ ├── README.md # Directory index │ └── getting-started.md └── projects/ └── project-a.md ```
## Frontmatter Configuration Each article must start with metadata in YAML format: ```yaml
title: Article Title (required) description: Article description pubDate: 2025-01-05 author: Author name tags: [tag1, tag2] categories: [category] draft: false star: false
```
## Required and Optional Fields | Field | Required | Description | |------|:----:|------| | `title` | ✅ | Article title | | `pubDate` | ✅ | Publication date | | `description` | - | SEO description | | `author` | - | Author name | | `tags` | - | Tag list | | `categories` | - | Categories | | `draft` | - | Draft status |
## URL Mapping Rules File path determines access URL: | File Path | Access URL | |----------|----------| | `posts/hello.md` | `/posts/hello` | | `posts/guide/intro.md` | `/posts/guide/intro` | | `posts/guide/README.md` | `/posts/guide` |
# Chapter 4 ## Featured Functions
## Tip Containers Six preset container styles: ```markdown ::: tip Tip This is a tip message ::: ::: warning Warning This is a warning message ::: ::: danger Danger This is a danger warning ::: ```
## Container Types Overview | Type | Icon | Purpose | |------|------|------| | `tip` | 💡 | Tips and suggestions | | `info` | ℹ️ | Additional information | | `note` | 📝 | Important notes | | `warning` | ⚠️ | Warning reminders | | `danger` | 🚨 | Danger alerts | | `details` | 📋 | Collapsible content |
## Code Highlighting Supports 100+ programming languages: ````markdown ```javascript function hello(name) { console.log(`Hello, ${name}!`); } ``` ```python def hello(name): print(f"Hello, {name}!") ``` ````
## Mathematical Formulas Use LaTeX syntax: **Inline formula:** `$E = mc^2$` **Block formula:** ```latex $$ \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} $$ ```
## Mermaid Flowcharts ````markdown ```mermaid graph TD A[Start] --> B{Condition} B -->|Yes| C[Execute] B -->|No| D[Skip] C --> E[End] D --> E ``` ````
## Mermaid Chart Types - **Flowcharts** - `graph TD/LR/BT/RL` - **Sequence Diagrams** - `sequenceDiagram` - **Class Diagrams** - `classDiagram` - **Gantt Charts** - `gantt` - **Pie Charts** - `pie` - **State Diagrams** - `stateDiagram-v2`
## ECharts Charts Interactive charts supported in slides: ````markdown ```echarts { "xAxis": { "type": "category", "data": ["A", "B", "C"] }, "yAxis": { "type": "value" }, "series": [{ "data": [120, 200, 150], "type": "bar" }] } ``` ````
# Chapter 5 ## Slide Presentations
## Three Usage Methods | Method | Location | Description | |------|------|------| | Independent slides | `content/slides/` | Dedicated presentation pages | | Article slides | `content/posts/` | `layout: slides` | | Embedded slides | `.mdx` files | `<Slides>` component |
## Method 1: Independent Slides Create files in `content/slides/`: ```markdown
title: My Presentation theme: black slideNumber: true
# First Page Content...
# Second Page Use `---` to separate slides ```
## Method 2: Article Slides Set `layout: slides` in frontmatter: ```yaml
title: Tech Sharing pubDate: 2025-01-05 layout: slides theme: white transition: fade
``` The entire article will render as slides
## Method 3: Embedded Slides Use component in `.mdx` files: ```jsx import Slides from '@/components/media/Slides.astro'; <Slides src="/slides/demo" height="400px" /> // Or inline content <Slides height="400px"> # Title Content... </Slides> ```
## Slide Separators | Separator | Direction | Description | |--------|------|------| | `---` | Horizontal ➡️ | Main content | | `----` | Vertical ⬇️ | Section sub-content | ```markdown # Chapter 1 (Press →)
# Chapter 2
## 2.1 Details (Press ↓)
## 2.2 More
# Chapter 3 ```
## Available Themes | Theme | Style | |------|------| | `black` | Black background (default) | | `white` | White background | | `league` | Dark gray business style | | `night` | Deep blue night mode | | `solarized` | Developer color scheme | | `moon` | Deep blue moonlight style |
## Keyboard Shortcuts | Key | Function | |------|------| | `→` / `Space` | Next page | | `←` | Previous page | | `↑` / `↓` | Vertical navigation | | `Esc` / `O` | Overview mode | | `F` | Full screen | | `S` | Speaker view |
# Chapter 6 ## Configuration Customization
## Site Configuration Edit `src/config/site.ts`: ```typescript export const siteConfig = { title: "My Blog", description: "Blog description", author: "Author name", email: "email@example.com", avatar: "/avatar.png", } ```
## Social Links Edit `src/config/social.ts`: ```typescript export const socialLinks = [ { name: 'GitHub', url: 'https://github.com/xxx' }, { name: 'Twitter', url: 'https://twitter.com/xxx' }, { name: 'Email', url: 'mailto:xxx@example.com' }, ] ```
## Navigation Menu Edit `src/config/menu.ts`: ```typescript export const menuItems = [ { title: 'Home', path: '/' }, { title: 'Blog', path: '/posts' }, { title: 'About', path: '/about' }, ] ```
# Chapter 7 ## Deployment
## Build Production Version ```bash # Build npm run build # Local preview npm run preview ``` Build output in `dist/` directory
## Deployment Platforms | Platform | Features | |------|------| | **Vercel** | Zero configuration, auto deploy | | **Netlify** | Feature-rich, CDN acceleration | | **GitHub Pages** | Free, suitable for open source projects | | **Cloudflare Pages** | Global CDN, fast speed |
## Vercel Deployment 1. Push code to GitHub 2. Import project in Vercel 3. Automatically detect Astro framework 4. Click Deploy Auto-updates on every push!
## GitHub Pages Deployment ```yaml # .github/workflows/deploy.yml 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 - run: npm install && npm run build - uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./dist ```
# Summary
## Key Points Review <p class="fragment">📁 Content in `content/posts/` directory</p> <p class="fragment">📝 Write using Markdown + Frontmatter</p> <p class="fragment">✨ Use containers, code blocks, charts and other features</p> <p class="fragment">🎬 Three ways to create slides</p> <p class="fragment">⚙️ Personalize through config files</p> <p class="fragment">🚀 One-click deploy to major platforms</p>
## Learning Resources - 📚 **Blog Documentation** - `/posts/blog_docs/` - 🎯 **Example Slides** - `/slides/demo` - 🔗 **Astro Website** - astro.build - 🔗 **Reveal.js** - revealjs.com - 🔗 **Mermaid** - mermaid.js.org
## Start Creating! ```bash # Create your first article touch content/posts/my-first-post.md # Start development server npm run dev # Start writing ✍️ ```
# Thank You! Questions welcome for discussion Press `Esc` to view all slides overview