分析
摘要：基于 Lonetrail 博客主题特点整理的 Markdown 文档编写规范，包含 Frontmatter 字段定义、排版风格、代码高亮、数学公式及自定义组件的使用说明。
本文档旨在为 Lonetrail 博客平台的文章撰写制定统一的 Markdown 编写规范。通过遵循本规范，可以确保文章在主题渲染、排版美观度、功能可用性（如代码高亮、数学公式、自定义组件）以及检索优化（SEO）上达到最佳效果。
一、 Frontmatter 元数据规范
每篇博客文章的开头必须包含 YAML 格式的 Frontmatter 区域，用以定义文章的元数据。
1. 标准模板
PRTCL // YAML
---title: "文章标题"published: 2026-06-18description: "这是一段关于文章核心内容的简短摘要，用于文章列表展示及 SEO Meta 描述。"tags: ["标签一", "标签二"]category: "Tech"image: "/images/covers/demo-cover.webp"---2. 字段详细说明
| 字段名称 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
title | String | 是 | 文章标题。应尽量简炼且表达主题，两端使用双引号包裹。 |
published | Date | 是 | 发布日期。格式为 YYYY-MM-DD，无需加引号。 |
description | String | 是 | 文章简介 / 摘要。建议在 100-150 字之间，有利于列表卡片美观及 SEO 抓取。 |
tags | Array | 是 | 标签列表。用以进行标签页面的分类聚合。例如：["Go", "Concurrency"]。 |
category | String | 是 | 分类。全站主要的大分类之一，例如 Tech（技术）或 Journal（日志）。 |
image | String | 否 | 文章封面图路径。若无，请留空字符串 ""。 |
WARNING注意：禁止在正文中遗漏 Frontmatter。未包含 Frontmatter 的历史文档（如部分旧技术笔记）应及时补充此元数据，否则可能导致 Astro 渲染引擎读取属性失败或无法在归档 / 系列列表中正常展示。
二、 页面标题与结构规范
1. 标题层级
- 禁止在正文中使用一级标题 (
#)。 Astro 渲染器会自动将 Frontmatter 中的title解析并渲染为页面的<h1>标签。因此，文章正文的最高级标题必须从二级标题 (##) 开始。 - 合理使用三级标题 (
###) 和四级标题 (####) 进行内容细分，避免标题层级过深（一般不超过四级）。
2. 空行与间距
- 每个标题、段落、列表、代码块、引用块之间，必须保留且仅保留一个空行。
- 这样可以保证 Markdown 源码的可读性，并使得渲染后的排版间距符合视觉比例。
3. 中英文混排与排版细节
为了排版的美观性与专业性，建议在正文撰写中遵循以下细节：
- 空格使用：中文与英文、中文与数字之间建议保留一个半角空格。
- 推荐：我们在 Go 语言中经常使用 Goroutine 来处理并发。
- 不推荐：我们在 Go 语言中经常使用 Goroutine 来处理并发。
- 避免无用样式：严禁直接从 Notion 或其它富文本编辑器复制带有多余 HTML 标签的内容（例如带有
<font style="color:...">的文本），应尽量保持纯净的 Markdown 语法。
三、 代码块与高亮规范
Lonetrail 集成了功能强大的 astro-expressive-code 插件，支持多语言语法高亮、代码框标题、行号、折叠、高亮行等高级功能。
1. 语言标识符
编写代码块时，必须明确指定语言标识符，以便代码高亮引擎正确解析。
PRTCL // MARKDOWN
# 推荐写法```gofunc main() { fmt.Println("Hello, Lonetrail")}PRTCL // PLAINTEXT
常用标识符参考：`typescript`, `javascript`, `python`, `rust`, `go`, `yaml`, `bash`, `json`, `markdown`。
### 2. 行内代码
对于正文中提及的变量、函数名、文件名、配置项或终端命令，应使用反引号包裹：* 示例：调用 `calculateTrajectory(origin, destination)` 方法来计算轨道。
---
## 四、 数学公式规范 (KaTeX)
Lonetrail 支持通过 KaTeX 渲染数学公式。
### 1. 块级公式
单独成行的公式使用双美元符号 `$$` 包裹：
$$E = mc^2$$
$$v = \sqrt{\frac{2GM}{r}}$$
### 2. 行内公式
行内嵌入的数学公式使用单美元符号 `$` 包裹。例如：质能方程 $E=mc^2$ 描述了质量与能量的等价关系。
---
## 五、 自定义提示框与组件规范
基于 `rehype-components` 插件，Lonetrail 支持在 Markdown 中直接使用 HTML 自定义标签来渲染精美的提示框（Callout/Admonition）。
### 1. 提示框类型
根据 `astro.config.mjs` 中的配置，系统目前支持以下提示框标签：
| 标签对 | 别名标签（颜色） | 适用场景 | 渲染效果 || :--- | :--- | :--- | :--- || `<note>` | `<blue>` | 一般信息、补充说明 | 蓝色背景提示框 || `<tip>` | `<green>` | 实用技巧、最佳实践建议 | 绿色背景提示框 || `<important>`| `<cyan>` | 关键步骤、核心要点 | 青色背景提示框 || `<warning>` | `<yellow>` | 潜在风险、兼容性警告 | 黄色背景提示框 || `<caution>` | `<red>` | 高危操作、可能导致失败的细节 | 红色背景提示框 |
### 2. 使用方法示例
在 Markdown 正文中直接使用闭合标签包裹内容即可：
```html<note>这是一条蓝色的补充说明信息，用于提示读者某些不显眼但有用的细节。</note>
<tip>** 提示 **：在执行 `pnpm dev` 之前，确保已运行过 `pnpm install` 完整下载所有依赖。</tip>
<caution>** 警告 **：修改 `src/site.yml` 配置时，请保持正确的 YAML 缩进，否则可能导致构建报错。</caution>六、 引用与列表规范
1. 引用块
引用块使用 > 引导，通常用于引用名言、参考资料说明等。如需换行，需要在行末加上两个空格或直接使用空行：
Ad Astra Per Aspera.
Through hardships to the stars.
2. 列表
- 无序列表：使用
-或*作为引导符。 - 有序列表：使用数字加英文句点
1.，后面保留一个空格。 - 嵌套列表：子列表的引导符相比上级列表需要缩进 2 或 4 个空格。
R P
莱茵实验室先锋部
认证_已验证: 2026.06.18
认证_已验证: 2026.06.18
