博客模板使用指南
本指南将帮助你了解如何编写Markdown文章，以及我在构建这个博客模板时使用的技术。
一、Markdown文件的基本结构
每个Markdown文件都需要在最上方添加 frontmatter（前置元数据），这是告诉Astro如何处理这个文件的配置信息。
必需的frontmatter格式
---
layout: ../../layouts/MarkdownLayout.astro
title: '文章标题'
pubDate: 2024
description: '文章描述，会显示在标题下方'
author: '作者名'
tags: ["标签1", "标签2", "标签3"]
---frontmatter字段说明
| 字段 | 必需 | 说明 |
|---|---|---|
layout | 是 | 指定使用的布局模板，固定写法 |
title | 是 | 文章标题，显示在页面顶部 |
pubDate | 否 | 发布日期，如 2024 或 2024-01-13 |
description | 否 | 文章描述/副标题 |
author | 否 | 作者名称 |
tags | 否 | 标签数组，如 ["AI", "技术"] |
二、Markdown语法速查
标题
# 一级标题
## 二级标题
### 三级标题效果：一级标题会有下划线装饰，二级标题有左侧边框装饰。
段落和文本
普通段落直接写就行。
**加粗文本**
*斜体文本*
`行内代码`列表
- 无序列表项1
- 无序列表项2
1. 有序列表项1
2. 有序列表项2链接
[链接文字](https://example.com)代码块
使用三个反引号包裹，可以指定语言：
```javascript
const hello = "world";
console.log(hello);
```引用
> 这是一段引用文字
> 可以多行引用效果就像这样
分割线
---表格
| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 内容1 | 内容2 | 内容3 |三、页面布局结构解释
我在Astro页面中使用的HTML结构
<header class="page-header">
<h1>页面标题</h1>
<p class="page-subtitle">副标题</p>
</header>语法解释：
<header>- HTML5语义化标签，表示页面或区块的头部class="page-header"- CSS类名，用于添加样式<h1>- 一级标题标签<p>- 段落标签
区块结构
<section class="content-section">
<h2>区块标题</h2>
<div class="card-grid">
<!-- 卡片内容 -->
</div>
</section><section>- 表示一个独立的内容区块<div>- 通用容器，用于分组元素
卡片组件
<a href="/posts/post1/" class="card">
<span class="card-title">文章标题</span>
<span class="card-arrow">→</span>
</a><a href="...">- 链接标签<span>- 行内元素，用于包装文本
四、CSS样式说明
CSS变量（颜色系统）
在 global.css 中定义的颜色变量：
:root {
--color-bg: #1a1a1a; /* 主背景色 */
--color-bg-secondary: #242424; /* 卡片背景 */
--color-text: #e5e5e5; /* 主文本色 */
--color-text-secondary: #a3a3a3; /* 次要文本 */
--color-border: #404040; /* 边框颜色 */
}常用类名和作用
| 类名 | 作用 |
|---|---|
.page-header | 页面头部样式，居中、有底部边框 |
.content-section | 内容区块，有下边距 |
.card | 卡片样式，悬浮有动画效果 |
.article-content | Markdown内容容器 |
五、写文章时的注意事项
1. 路径问题
layout的路径是相对于当前文件的：
-
如果文章在
src/pages/posts/目录下：layout: ../../layouts/MarkdownLayout.astro -
如果文章在
src/pages/skill/目录下：layout: ../../layouts/MarkdownLayout.astro
2. 文件命名
- 文件名会成为URL，如
post1.md→/posts/post1/ - 支持中文文件名，如
交错思维链.md→/skill/交错思维链/ - 建议使用小写字母和连字符，如
my-first-post.md
3. 图片使用
图片会自动获得圆角和边框样式。
4. 代码高亮
行内代码使用反引号：code
代码块效果：
- 橙色高亮的行内代码
- 暗色背景的代码块
- 支持语法高亮
5. 段落间距
每个段落之间空一行，这样输出的排版会更好看。
六、新建文章模板
复制以下内容作为新文章的起点：
---
layout: ../../layouts/MarkdownLayout.astro
title: '文章标题'
pubDate: 2024
description: '文章描述'
author: '博主'
tags: ["标签1", "标签2"]
---
# 文章正文标题
这里是文章内容...
## 第一部分
内容...
## 第二部分
内容...
---
**总结**：这里写总结。七、首页添加文章链接
如果想把新文章添加到首页，需要编辑 src/pages/index.astro：
<a href="/posts/新文章名/" class="card">
<span class="card-title">新文章标题</span>
<span class="card-arrow">→</span>
</a>希望这个指南对你有帮助！如有问题，随时查阅本文档。