@jet-w/astro-blog 0.1.0

package/templates/default/content/posts/blog_docs/03-markdown-basic.md

@@ -0,0 +1,350 @@
+---
+title: Markdown 基础语法
+description: 标准 Markdown 语法快速参考
+pubDate: 2025-12-11
+author: Astro Blog
+categories:
+  - 博客教程
+tags:
+  - Markdown
+  - 语法
+---
+
+# Markdown 基础语法
+
+本文回顾 Markdown 的基础语法，帮助你快速上手文章写作。
+
+## 标题
+
+使用 `#` 号创建标题，`#` 数量表示标题级别：
+
+```markdown
+# 一级标题
+## 二级标题
+### 三级标题
+#### 四级标题
+##### 五级标题
+###### 六级标题
+```
+
+::: tip 建议
+- 文章正文从二级标题 `##` 开始
+- 一级标题 `#` 用于文章主标题
+- 保持标题层级的连贯性
+:::
+
+## 段落与换行
+
+**段落**：空行分隔
+
+```markdown
+这是第一段。
+
+这是第二段。
+```
+
+**换行**：行尾两个空格，或使用 `<br>`
+
+```markdown
+第一行
+第二行
+
+或者
+
+第一行<br>第二行
+```
+
+## 文本样式
+
+| 样式 | 语法 | 效果 |
+|:---|:---|:---|
+| 粗体 | `**粗体**` | **粗体** |
+| 斜体 | `*斜体*` | *斜体* |
+| 粗斜体 | `***粗斜体***` | ***粗斜体*** |
+| 删除线 | `~~删除线~~` | ~~删除线~~ |
+| 行内代码 | `` `code` `` | `code` |
+
+## 列表
+
+### 无序列表
+
+```markdown
+- 项目一
+- 项目二
+  - 子项目 2.1
+  - 子项目 2.2
+- 项目三
+```
+
+效果：
+
+- 项目一
+- 项目二
+  - 子项目 2.1
+  - 子项目 2.2
+- 项目三
+
+### 有序列表
+
+```markdown
+1. 第一步
+2. 第二步
+3. 第三步
+   1. 子步骤 3.1
+   2. 子步骤 3.2
+```
+
+效果：
+
+1. 第一步
+2. 第二步
+3. 第三步
+   1. 子步骤 3.1
+   2. 子步骤 3.2
+
+### 任务列表
+
+```markdown
+- [x] 已完成任务
+- [ ] 未完成任务
+- [ ] 待办事项
+```
+
+效果：
+
+- [x] 已完成任务
+- [ ] 未完成任务
+- [ ] 待办事项
+
+## 链接
+
+### 基本链接
+
+```markdown
+[链接文字](https://example.com)
+[带标题的链接](https://example.com "鼠标悬停提示")
+```
+
+效果：[链接文字](https://example.com)
+
+### 内部链接
+
+```markdown
+[查看快速开始](./01-quick-start)
+[返回首页](/)
+[锚点链接](#标题)
+```
+
+### 自动链接
+
+```markdown
+<https://example.com>
+<email@example.com>
+```
+
+## 图片
+
+### 基本语法
+
+```markdown
+![替代文字](/images/example.jpg)
+![带标题的图片](/images/example.jpg "图片标题")
+```
+
+### 图片存放位置
+
+将图片放在 `public/images/` 目录下：
+
+```
+public/
+└── images/
+    ├── posts/
+    │   └── my-article/
+    │       └── screenshot.png
+    └── logo.png
+```
+
+引用方式：
+
+```markdown
+![截图](/images/posts/my-article/screenshot.png)
+```
+
+::: tip 图片命名建议
+- 使用有意义的文件名
+- 使用小写字母和连字符
+- 按文章组织图片目录
+:::
+
+## 引用
+
+```markdown
+> 这是一段引用文字。
+> 可以有多行。
+>
+> > 嵌套引用
+```
+
+效果：
+
+> 这是一段引用文字。
+> 可以有多行。
+>
+> > 嵌套引用
+
+## 代码
+
+### 行内代码
+
+```markdown
+使用 `console.log()` 输出日志。
+```
+
+效果：使用 `console.log()` 输出日志。
+
+### 代码块
+
+````markdown
+```javascript
+function hello(name) {
+  console.log(`Hello, ${name}!`);
+}
+```
+````
+
+效果：
+
+```javascript
+function hello(name) {
+  console.log(`Hello, ${name}!`);
+}
+```
+
+详见 [代码块与高亮](./05-code-blocks)。
+
+## 表格
+
+```markdown
+| 左对齐 | 居中对齐 | 右对齐 |
+|:-------|:--------:|-------:|
+| 内容1  | 内容2    | 内容3  |
+| 内容4  | 内容5    | 内容6  |
+```
+
+效果：
+
+| 左对齐 | 居中对齐 | 右对齐 |
+|:-------|:--------:|-------:|
+| 内容1  | 内容2    | 内容3  |
+| 内容4  | 内容5    | 内容6  |
+
+::: info 对齐方式
+- `:---` 左对齐
+- `:---:` 居中对齐
+- `---:` 右对齐
+:::
+
+## 分隔线
+
+```markdown
+---
+
+***
+
+___
+```
+
+效果：
+
+---
+
+## 脚注
+
+```markdown
+这是一段带脚注的文字[^1]。
+
+[^1]: 这是脚注的内容。
+```
+
+## 转义字符
+
+使用反斜杠 `\` 转义特殊字符：
+
+```markdown
+\*不是斜体\*
+\# 不是标题
+\[不是链接\]
+```
+
+效果：\*不是斜体\*
+
+## HTML 支持
+
+Markdown 中可以直接使用 HTML：
+
+```markdown
+<details>
+<summary>点击展开</summary>
+
+这是隐藏的内容。
+
+</details>
+
+<kbd>Ctrl</kbd> + <kbd>C</kbd>
+```
+
+效果：
+
+<details>
+<summary>点击展开</summary>
+
+这是隐藏的内容。
+
+</details>
+
+快捷键：<kbd>Ctrl</kbd> + <kbd>C</kbd>
+
+## 最佳实践
+
+### 1. 保持简洁
+
+```markdown
+# 好的写法
+使用 **重点** 标记关键词。
+
+# 避免过度使用
+使用 ***非常非常*** **重要的** *关键* ~~词~~。
+```
+
+### 2. 合理使用列表
+
+```markdown
+# 适合用列表
+功能特点：
+- 快速
+- 简单
+- 强大
+
+# 不适合用列表（改用段落）
+这是一个关于...的说明，它包含了...的内容。
+```
+
+### 3. 代码与说明配合
+
+```markdown
+使用 `map()` 方法遍历数组：
+
+```javascript
+const doubled = [1, 2, 3].map(x => x * 2);
+```
+
+这会返回 `[2, 4, 6]`。
+```
+
+## 下一步
+
+掌握基础语法后，学习本博客的增强功能：
+
+- [容器语法](./04-containers) - 提示框、警告框等
+- [代码块与高亮](./05-code-blocks) - 代码展示最佳实践
+- [Mermaid 图表](./06-mermaid) - 绘制流程图等

package/templates/default/content/posts/blog_docs/04-containers.md

@@ -0,0 +1,331 @@
+---
+title: 容器语法
+description: 使用提示框、警告框等容器增强文章表现力
+pubDate: 2025-12-11
+author: Astro Blog
+categories:
+  - 博客教程
+tags:
+  - 容器
+  - Markdown
+---
+
+# 容器语法
+
+容器是本博客的特色功能，用于创建醒目的提示框、警告框等，让文章更加清晰易读。
+
+## 基本语法
+
+```markdown
+::: 类型 可选标题
+容器内容
+:::
+```
+
+## 容器类型
+
+本博客支持 6 种容器类型：
+
+### tip - 提示
+
+```markdown
+::: tip
+这是一个提示信息。
+:::
+
+::: tip 自定义标题
+这是带自定义标题的提示。
+:::
+```
+
+::: tip
+这是一个提示信息。
+:::
+
+::: tip 自定义标题
+这是带自定义标题的提示。
+:::
+
+### info - 信息
+
+```markdown
+::: info
+这是一条信息说明。
+:::
+
+::: info 补充说明
+关于这个功能的更多信息...
+:::
+```
+
+::: info
+这是一条信息说明。
+:::
+
+::: info 补充说明
+关于这个功能的更多信息...
+:::
+
+### note - 注意
+
+```markdown
+::: note
+请注意这一点。
+:::
+
+::: note 注意事项
+使用时需要注意以下几点...
+:::
+```
+
+::: note
+请注意这一点。
+:::
+
+::: note 注意事项
+使用时需要注意以下几点...
+:::
+
+### warning - 警告
+
+```markdown
+::: warning
+这是一条警告信息。
+:::
+
+::: warning 版本兼容性
+此功能仅在 v2.0 以上版本可用。
+:::
+```
+
+::: warning
+这是一条警告信息。
+:::
+
+::: warning 版本兼容性
+此功能仅在 v2.0 以上版本可用。
+:::
+
+### danger - 危险
+
+```markdown
+::: danger
+危险操作，请谨慎！
+:::
+
+::: danger 数据丢失风险
+此操作将永久删除数据，无法恢复！
+:::
+```
+
+::: danger
+危险操作，请谨慎！
+:::
+
+::: danger 数据丢失风险
+此操作将永久删除数据，无法恢复！
+:::
+
+### details - 详情（可折叠）
+
+```markdown
+::: details
+这是可以折叠的内容。
+:::
+
+::: details 点击查看详情
+这里是隐藏的详细内容。
+
+可以包含多段文字。
+:::
+```
+
+::: details
+这是可以折叠的内容。
+:::
+
+::: details 点击查看详情
+这里是隐藏的详细内容。
+
+可以包含多段文字。
+:::
+
+## 容器内容
+
+### 支持多行文本
+
+```markdown
+::: tip 多行内容
+第一行内容。
+
+第二行内容。
+
+第三行内容。
+:::
+```
+
+::: tip 多行内容
+第一行内容。
+
+第二行内容。
+
+第三行内容。
+:::
+
+### 支持列表
+
+```markdown
+::: info 功能特点
+- 特点一：快速响应
+- 特点二：简单易用
+- 特点三：功能强大
+:::
+```
+
+::: info 功能特点
+- 特点一：快速响应
+- 特点二：简单易用
+- 特点三：功能强大
+:::
+
+### 支持代码
+
+```markdown
+::: tip 代码示例
+使用以下代码：
+\`\`\`javascript
+console.log('Hello');
+\`\`\`
+:::
+```
+
+::: tip 代码示例
+使用以下代码：
+```javascript
+console.log('Hello');
+```
+:::
+
+### 支持链接和格式
+
+```markdown
+::: note 参考资料
+更多信息请查看 [官方文档](https://example.com)。
+
+重点内容用 **粗体** 标记。
+:::
+```
+
+::: note 参考资料
+更多信息请查看 [官方文档](https://example.com)。
+
+重点内容用 **粗体** 标记。
+:::
+
+## 使用场景
+
+### 教程中的提示
+
+::: tip 快捷键
+使用 `Ctrl + S` 保存文件。
+:::
+
+### API 文档中的注意事项
+
+::: warning 废弃警告
+`oldFunction()` 已废弃，请使用 `newFunction()` 代替。
+:::
+
+### 操作指南中的警告
+
+::: danger 破坏性操作
+执行此命令前请确保已备份数据：
+```bash
+rm -rf /data/*
+```
+:::
+
+### 补充说明
+
+::: details 实现原理
+这个功能基于以下技术实现：
+
+1. 使用 remark-directive 解析自定义语法
+2. 通过 remark-containers 插件转换为 HTML
+3. 使用 Tailwind CSS 进行样式化
+
+代码实现位于 `src/plugins/remark-containers.mjs`。
+:::
+
+## 样式对照表
+
+| 类型 | 颜色 | 图标 | 适用场景 |
+|:---|:---|:---|:---|
+| tip | 蓝色 | 💡 | 有用的建议、技巧 |
+| info | 蓝色 | ℹ️ | 补充信息、说明 |
+| note | 灰色 | 📝 | 注意事项、备注 |
+| warning | 黄色 | ⚠️ | 警告、注意 |
+| danger | 红色 | 🚨 | 危险操作、严重警告 |
+| details | 灰色 | 📋 | 可折叠的详细内容 |
+
+## 最佳实践
+
+### 1. 选择合适的类型
+
+```markdown
+<!-- 好：选择合适的类型 -->
+::: tip 性能提示
+启用缓存可以提升 50% 的加载速度。
+:::
+
+<!-- 不好：类型与内容不匹配 -->
+::: danger 性能提示
+启用缓存可以提升 50% 的加载速度。
+:::
+```
+
+### 2. 保持内容简洁
+
+```markdown
+<!-- 好：简洁明了 -->
+::: warning
+Node.js 版本需要 >= 18.0
+:::
+
+<!-- 不好：内容过长 -->
+::: warning
+这是一个非常长的警告信息，包含了很多不必要的内容...
+（应该拆分或简化）
+:::
+```
+
+### 3. 添加有意义的标题
+
+```markdown
+<!-- 好：标题说明内容 -->
+::: info 环境要求
+- Node.js >= 18.0
+- npm >= 9.0
+:::
+
+<!-- 一般：使用默认标题 -->
+::: info
+- Node.js >= 18.0
+- npm >= 9.0
+:::
+```
+
+### 4. 避免过度使用
+
+一篇文章中不要使用过多的容器，否则会分散读者注意力。建议：
+
+- 每个章节最多 2-3 个容器
+- 只在确实需要强调的地方使用
+- details 容器适合放置参考信息
+
+## 下一步
+
+继续学习其他增强功能：
+
+- [代码块与高亮](./05-code-blocks) - 代码展示最佳实践
+- [Mermaid 图表](./06-mermaid) - 绘制各类图表