解析器 (Parser)
Snow 通过内容解析器把 .md、.org、.html 文件转换为统一的 Page / Section 数据。
内置解析器
| 解析器 | 扩展名 | 引擎 | 默认启用 | 说明 |
|---|---|---|---|---|
markdown |
.md |
goldmark | 是 | Markdown 内容，支持 YAML/TOML FrontMatter |
orgmode |
.org |
org-golang | 是 | 默认 Org-mode 解析器 |
niklasfasching |
.org |
niklasfasching/go-org | 否 | 可选 Org-mode 解析器 |
html |
.html |
Go HTML parser | 否 | HTML 文档或片段 |
HTML 和 niklasfasching parser 已在 CLI 中注册，但默认未启用。需要使用时在 markups 中开启：
1markups: 2 html: 3 enabled: true 4 niklasfasching: 5 enabled: true
orgmode 和 niklasfasching 都处理 .org 文件。如果同时启用，当前注册顺序下 niklasfasching 会优先接管 .org，默认的 orgmode 不再处理同一扩展名。
元数据
| 格式 | 元数据来源 |
|---|---|
| Markdown | YAML ---、TOML +++、或文件开头的 key: value 行 |
| Org-mode | :PROPERTIES: drawer、文件开头的 #+KEY:、#+PROPERTY: |
| HTML | <head> 中的 <title>、<meta>、<link>、<script> |
Markdown FrontMatter 示例：
1--- 2title: "我的文章" 3date: 2024-01-15 4tags: 5 - go 6 - web 7draft: false 8---
启用 markups.markdown.directive_blocks 后，Markdown 支持类似 Org-mode 的指令块：
1markups: 2 markdown: 3 directive_blocks: true
1:::export html 2<div class="raw-html"> 3 <span>原样输出 HTML</span> 4</div> 5::: 6 7:::center 8这里的 **Markdown** 会继续解析，并包裹在 `<div style="text-align: center;">` 中。 9::: 10 11:::quote 12这里的 **Markdown** 会继续解析，并包裹在 `<blockquote>` 中。 13::: 14 15:::shortcode notice type=info 16这里的 **Markdown** 会继续解析，并作为 shortcode body 传入。 17 18- static-site 19- go 20:::
:::shortcode 是 Markdown 指令块中的短代码写法，详细用法见 短代码 (Shortcode)。
HTML parser 会把 <head> 中的标签转换为 FrontMatter：
| HTML 标签 | 写入字段 |
|---|---|
<title> |
title |
<meta name="date" content="..."> |
date |
<meta property="og:title" content="..."> |
og.title |
<meta itemprop="description" content="..."> |
description |
<link rel="stylesheet" href="..."> |
追加到 links |
<script src="..."> |
追加到 scripts |
正文与摘要
| 格式 | 正文来源 | 摘要分隔符 |
|---|---|---|
| Markdown | Markdown 渲染结果 | <!--more--> |
| Org-mode | Org 渲染结果 | #+snow: more 或 #+html: <!--more--> |
| HTML | <body> 子节点；没有完整文档结构时把 HTML 片段作为正文 |
<!--more--> |
Org-mode 的摘要分隔符使用 Snow 专用 keyword：
1summary 2#+snow: more 3content
也可以使用导出 HTML keyword，便于沿用已有 Org 内容：
1summary 2#+html: <!--more--> 3content
Toc
启用 markups._default.show_toc 或对应 parser 的 show_toc 后，解析器会生成 Toc。
Markdown 和 Org-mode 根据标题结构生成目录。HTML parser 会扫描 h1-h6，保留已有 id，并为缺少 id 的标题自动补上 heading-...。
markups._default.toc_id 或对应 parser 的 toc_id 可切换自动生成的锚点：
| 值 | 说明 |
|---|---|
title |
默认值，使用标题文本生成锚点，例如 Hello World 生成 hello-world，中文会保留 |
index |
使用 heading-1、heading-1.1 这类稳定编号 |
模板 Filter
| Filter | 说明 |
|---|---|
parser:"markdown" |
使用 Markdown parser 把字符串转为 HTML |
parser:"orgmode" |
使用默认 Org-mode parser 把字符串转为 HTML |
parser:"niklasfasching" |
使用 niklasfasching/go-org 把字符串转为 HTML；只有 markups.niklasfasching.enabled: true 时可用 |
parser filter 只会调用当前配置中已启用的解析器。解析器未启用或格式名不存在时，模板渲染会返回错误。
错误处理与限制
Markdown 与 Org-mode 解析器支持最长约 1MB 的单行内容。Markdown FrontMatter 必须使用同类型 fence 闭合；Org-mode 的 :PROPERTIES: drawer 必须以 :END: 闭合，否则构建会报错。
HTML parser 基于 Go HTML tree parser。解析错误会直接返回并中止构建。