一颗丁子

简单的博客渲染器

这里用来测试博客的 md 解析和渲染能力。

目录

段落与行内样式

普通段落会按照窄内容布局排版。中文、英文和数字可以自然混排，例如：这个渲染器用于一个 SSG 博客，文章在构建时被转换成 HTML，前端只接收已经准备好的内容。

行内样式包括 强调、加粗、删除线 和 inline code。这些样式适合用于解释命令、变量名或简短状态，例如 pnpm build、public/blogs 和 data-theme-mode。

如果需要手动换行，可以在行尾加两个空格。
这一行会紧跟上一行，但仍然保留明确的换行语义。

列表与任务

无序列表适合记录松散的能力点：

  • 文章标题来自第一条 Markdown 标题。
  • 图片资源会在编译时解析为 public 下的前端路径。
  • 站内博客链接会被解析成 /blog/slug。
  • 指向章节的 hash 会被保留，用于跳转和悬浮预览。

有序列表适合表达流程：

  1. 在 public/blogs 下创建文章目录。
  2. 在目录里编写 index.md。
  3. 运行 pnpm build。
  4. 检查 dist/client 里的预渲染结果。

GFM 任务列表可以表达状态：

  • 支持 GFM 表格、任务列表和删除线。
  • 支持代码块高亮。
  • 支持脚注互相跳转。
  • 未来可以继续增加目录自动生成。

引用块

引用块适合放一段需要被强调但不应该变成标题的内容。

这个博客项目的目标不是把 Markdown 变成复杂 CMS，而是让写作路径尽量直接：文件放在 public 中，文章引用资源时使用自然的相对路径，构建阶段负责解析这些路径。

引用块内部也可以包含 加粗文本、inline code 和列表：

  • 保持内容可读。
  • 保持构建结果稳定。
  • 保持前端组件轻量。

链接与站内预览

普通外链会保持原样，例如 Vike 官网。外链不会触发站内预览。

指向当前文章章节的链接会保留 hash，例如 跳到代码块。鼠标悬浮这类内部 hash 链接时，也应该显示对应位置的渲染预览。

指向博客 Markdown 文件的链接会在编译时转换成博客路由。下面这个链接虽然写的是 public 内的 Markdown 文件，但构建后应该指向当前文章页面，并保留章节 hash：查看脚注章节。

也可以使用相对路径写同样的引用：回到目录。

图片与资源路径

图片可以使用 public 目录内的路径。下面这张图来自根目录的 public/favicon.svg，它同时也是当前站点的 favicon：

博客图标示例

资源链接也可以带 title 文本，构建时只会重写 URL 部分，不会吞掉后面的说明：打开图标资源。

表格

表格适合对比渲染器各阶段的职责：

阶段 输入 输出 主要职责
读取 index.md Markdown 文本 从 public 目录读取文章
解析 Markdown AST HAST 处理 GFM、链接和图片
增强 HAST HAST 添加标题 id、代码高亮
输出 HAST HTML 字符串 交给 Vike 预渲染

对齐语法也可以工作：

项目 状态 备注
图片路径 完成 支持空格
脚注 完成 支持返回
代码块 完成 深色高亮

代码块

没有声明语言的代码块会按普通文本显示：

public/blogs/1781577987795-first-of-all/index.md
public/favicon.svg

声明语言后会使用 GitHub 风格的深色代码高亮。TypeScript 示例：

type BlogLink = {
  slug: string;
  hash?: string;
};

const blogPath = ({ slug, hash = "" }: BlogLink) => {
  return `/blog/${slug}${hash}`;
};

console.log(blogPath({ slug: "first-of-all", hash: "#代码块" }));

Shell 示例：

pnpm fmt
pnpm typecheck
pnpm lint
pnpm test
pnpm build

即使语言名写错，渲染器也会退回普通文本高亮，而不是让构建失败：

这段代码块的语言名不存在，但文章仍然应该可以构建。

脚注

脚注适合补充解释，不打断正文阅读。这里有一个脚注引用1，也有第二个脚注引用2。点击脚注编号应该跳到页面底部的脚注内容，点击脚注后的返回箭头应该回到正文位置。

分隔线

下面是一条水平分隔线。它适合在长文章里切分主题，但不应该替代标题结构。

这篇展示文档到这里结束。后续如果渲染器支持新的语法能力，可以继续在本文追加一个章节，并补充对应的构建测试。

Footnotes

  1. SSG 指 Static Site Generation。这个项目会在构建阶段预先生成 HTML，因此文章渲染逻辑应该尽量留在服务端构建流程中。 ↩

  2. 路径重解析让作者可以在 Markdown 中自然引用 public 目录内的资源，而不用手动计算最终前端 URL。 ↩

修改于