写代码，也记录一路学到的东西。这里记录我做过的项目、开发中遇到的问题，以及试过的工具和方法。希望这些文章能帮未来的自己少走些弯路，也给同行留下一点参考。https://example.com/zh-CNhttps://example.com/posts/markdown-style-guide/https://example.com/posts/markdown-style-guide/这是一篇示例文章，用于演示本博客支持的 Markdown 元素——标题、列表、引用、表格、代码块、图片等。确认排版效果后，可以直接删除或替换它。Tue, 20 Oct 2026 00:00:00 GMT> 这是一篇**示例文章**，用来展示博客支持的写作元素和排版效果。熟悉之后，直接删除或改写它即可。 ## 基础排版 正文写在这里。中文段落之间会保持舒适的间距，行高经过调整，适合长时间阅读。你可以使用**加粗**、*斜体*、~~删除线~~，也可以插入[链接](https://www.example.com/)和行内代码 `const x = 1`。 一级标题（`#`）不需要写——文章标题来自 frontmatter 的 `title` 字段，正文里从 `##` 二级标题开始即可，它们会自动出现在右侧目录里。 ### 无序列表 - 支持多级列表 - 像这样 - 长列表项会正常折行，缩进保持整齐，不会出现悬挂问题 ### 有序列表 1. 第一步：在 `src/content/blog/` 新建一个 `.md` 文件 2. 第二步：填写 frontmatter（标题、摘要、日期、标签） 3. 第三步：开始写作，保存后开发服务器会热更新 ## 引用 引用块适合放摘录或强调的话： > 写作是一种思考的方式，而不是思考结果的表达。 > —— 一句用来演示引用样式的占位文字 ## 代码块 代码块使用 Shiki 高亮，浅色和深色主题下各自有一套配色： ```js title="reading-time.js" verified=2026-10-25 hl="2,4" // 阅读时长就是这样估算出来的 export function readingMinutes(body) { const cjk = (body.match(/[\u4e00-\u9fff]/g) ?? []).length; const latin = (body.match(/[A-Za-z0-9]+/g) ?? []).length; return Math.max(1, Math.round(cjk / 350 + latin / 200)); } ``` 第 2、4 行会被高亮（围栏 meta 写 `hl="2,4"`）。点击任意一行可以复制那一行。 ### Mermaid 图表 围栏语言写 `mermaid`，直接渲染流程图 / 时序图 / 类图（浅深色主题自适应）： ```mermaid flowchart LR A[写文章] --> B{需要图表?} B -- 是 --> C[写 mermaid 围栏] B -- 否 --> D[直接发布] C --> D ``` ### 代码行深链 按住 **Alt + 点击代码行**会复制 `文章链接#L行号`，别人打开链接自动高亮该行（Shift+Alt+点击复制当前行到文末的范围）。 ### 多版本代码 Tab 两个连续的代码块写同样的 `tab="组名"`，就会合并成一组可切换的标签页： ```js tab="防抖" title="debounce.js" export const debounce = (fn, ms = 300) => { let t; return (...args) => { clearTimeout(t); t = setTimeout(() => fn(...args), ms); }; }; ``` ```ts tab="防抖" title="debounce.ts" export const debounce = <A extends unknown[]>( fn: (...args: A) => void, ms = 300, ): ((...args: A) => void) => { let t: ReturnType<typeof setTimeout> | undefined; return (...args: A) => { clearTimeout(t); t = setTimeout(() => fn(...args), ms); }; }; ``` ### 交互式演示 围栏语言写 `html demo`，读者就能直接改代码、立刻看到效果： ```html demo <style> #demo-btn { padding: 10px 22px; font-size: 15px; border: 1px solid #b2452c; color: #b2452c; background: #fff; border-radius: 4px; cursor: pointer; } #demo-btn.on { background: #b2452c; color: #fff; } p { color: #57514a; } </style> <button id="demo-btn">点我试试</button> <p id="demo-out">还没点击</p> <script> let n = 0; document.getElementById('demo-btn').addEventListener('click', () => { n++; document.getElementById('demo-btn').classList.toggle('on', n % 2 === 1); document.getElementById('demo-out').textContent = `点击了 ${n} 次`; }); </script> ``` ## 表格 | 元素 | 写法 | 是否会出现在目录里 | | ------ | ------------------ | ------------------ | | 二级标题 | `## 标题` | 是 | | 三级标题 | `### 标题` | 是 | | 四级标题 | `#### 标题` | 否 | | 图片 | `` | 否 | ## 脚注 Markdown 脚注语法 `[^1]` 会渲染为文末注释，点击编号可跳转： 正文里插入脚注[^1]，也可以命名[^note]。读者点击编号会跳到文末的注释，再点 ↩ 跳回来。 [^1]: 这是第一个脚注的内容。 [^note]: 这是命名脚注的内容。 ## 图片 图片请放在 `public/images/` 目录下，然后用绝对路径引用。下面的图就是本站自带的一张示例图：  ### 新旧方案对照 围栏 meta 写 `refactor`，正文用单独一行 `====` 分隔新旧两版，并排展示（保留语法高亮）： ```js refactor // 旧方案：手写正则逐段判断 function oldWay(body) { return body.split(' ').filter((l) => l.startsWith('## ')); } ==== // 新方案：交给渲染管线，一行搞定 const headings = render(entry).headings.filter((h) => h.depth === 2); ``` ### 自测折叠块 围栏语言写 `text reveal`，内容默认遮住，读者点开才显示——适合先思考再看答案： ```text reveal 这是一段被遮住的解释。点击上方按钮后才会显示。 ``` ### 原理可视化 围栏写 `text viz bubble-sort`（或 `stack` / `waterfall`）可以嵌入内置的原理演示： ```text viz bubble-sort ``` ### 练习题 围栏写 `text exercises`，每行「任务 | 提示 | 参考答案」： ```text exercises 不用看上文，说出让代码块显示文件名的写法。 | 围栏 meta | 在语言后面写 title="文件名.js" 数一数本文有几个可交互的元素。 | demo、可视化、练习、选择题 | 四个 ``` ### 知识检查 围栏写 `text quiz`，每行「问题 | 选项（分号分隔） | 正确索引 | 解析」： ```text quiz 草稿文章会出现在生产构建的 RSS 里吗？ | 会;不会;只在本地会 | 1 | 草稿在全站（列表、RSS、搜索、归档）都被排除，只有本地 dev 能预览。 哪个字段给文章标注「内容仍有效」的最后确认时间？ | pubDate;lastVerified;updated | 1 | lastVerified 显示为文章页的验证徽标，超期还会提醒复查。 ``` ## 其他 ### 方案对比卡片 围栏语言写 `text compare`，每行按「名称 | 优点 | 缺点 | 适用场景 | 复杂度」书写，渲染成并列卡片： ```text compare 浅色主题 | 阅读负担小、印刷感 | 夜间刺眼 | 白天 / 长文阅读 | 低 深色主题 | 夜间舒适、省电（OLED） | 对比度设计要求高 | 夜间 / 暗环境 | 中 跟随系统 | 一次配置两端合适 | 用户无法主动干预 | 默认策略 | 低 ``` 写完正文后，分隔线之前的内容都会正常渲染： --- 最后提醒一下：这篇文章的 frontmatter 里 `featured: true`，所以它出现在首页的「精选文章」区域。不想展示就把这个字段删掉或改为 `false`。示例写作