Markdown 写作规范
这份规范用于维持 Hugoz’s Lab 的长期可读性。核心目标是让每篇文章都能回答三个问题：学了什么、为什么有用、如何复现。
1. 文章结构
课程与理论笔记
- 用一段话说明本章的问题和学习目标。
- 用
##划分主要章节，用###拆分知识点。 - 给出关键定义、推导、图示和结论。
- 记录尚未解决的问题，不把猜测写成定论。
工具与环境教程
- 先写适用环境和最终结果。
- 再写安装、配置和验证步骤。
- 命令放入带语言名称的代码块。
- 把版本、操作系统、路径等前提写清楚。
- 每个关键步骤都给出可观察的成功标志。
项目记录
- 问题背景与设计目标。
- 系统架构和接口。
- 关键实现决策及取舍。
- 仿真、综合或性能结果。
- 已知限制与下一步工作。
2. 标题层级
页面布局已经渲染文章标题，因此正文从 ## 开始。
-
##：章节 -
###：知识点或实现步骤 -
####：小结、公式含义或局部注意事项
不跳级使用标题，也不为了改变字号而滥用标题。
3. 开头和结论
开头用 2–4 句话交代：
- 当前问题是什么。
- 这篇文章要解决什么。
- 读者需要哪些前置知识。
如果文章较长，在开头增加“先看结论”：
> ##### TIP
>
> 本章的核心是：valid 不应等待 ready 后才拉高。
{: .block-tip }
4. 代码、命令与公式
- 行内代码只放符号、信号名、命令或文件名。
- 多行代码标注语言，例如
systemverilog、python、bash或powershell。 - 可运行示例应包含输入、命令和预期结果。
- 公式后紧跟变量含义和适用条件。
- 不用截图代替可复制的代码或日志。
5. 提示、警告与危险
只在需要改变读者行为时使用强调块：
> ##### WARNING
>
> 修改时钟约束后必须重新运行时序分析。
{: .block-warning }
-
.block-tip：建议、捷径或关键结论 -
.block-warning：常见错误或前提条件 -
.block-danger：可能造成数据丢失或破坏性后果的操作
6. 标签页
当同一任务有多种平台命令或多份对照代码时，才使用标签页。在 front matter 中设置 tabs: true，然后使用：
{% tabs terminal %}
{% tab terminal PowerShell %}
docker compose up -d
{% endtab %}
{% tab terminal Bash %}
docker compose up -d
{% endtab %}
{% endtabs %}
7. 图片与图表
- 图片只展示文字难以清楚表达的结构、时序或结果。
- 为每张图填写能独立理解的
title或图注。 - 优先使用 SVG 表示架构图，使用 PNG/WebP 表示截图。
- 图片保存到仓库内，不依赖可能失效的外部图床。
- Mermaid 页面需要在 front matter 中显式开启
mermaid.enabled。
8. 链接与引用
- 站内链接使用 Jekyll
link标签，避免手写域名和baseurl。 - 外部资料链接到原始论文、官方文档或项目仓库。
- 不使用“点击这里”作为链接文本，而是说明链接目标。
- 引用他人结论时区分原文事实与自己的推断。
9. 推荐模板
---
layout: post
title: "文章标题"
description: "一句话说明这篇文章解决什么问题。"
tags: [notes]
categories: [notes]
---
用 2–4 句话交代问题、目标和前置条件。
## 背景
## 核心原理
### 定义或架构
### 推导或实现
## 验证结果
## 小结与待办
10. 发布前检查
- 标题层级连续，没有重复的一级标题。
- 代码块、公式、表格和图片在桌面与手机宽度下都不溢出。
- 站内链接、图片和下载文件都能打开。
- 命令已在文中声明的环境中验证。
- 文章明确区分已完成、待验证和未解决内容。