文档章节
转换函数
用这些函数把取值从一种格式转换为另一种格式。
这一章把「一种表示」变成「另一种表示」:Markdown ↔ HTML、HTML → 纯文本、字符串 → 数据结构、数据结构 → JSON/YAML/TOML/XML、代码 → 高亮 HTML、LaTeX → 公式、Portable Text → Markdown。它们大多单向且有损,用之前先确认方向对不对。
本章也是「转义」类问题的集中地:htmlEscape、htmlUnescape、transform.XMLEscape 的返回值都是普通 string,在 HTML 模板里会被再次转义(实测,见各页完整示例);而 markdownify、plainify、jsonify、ToMath、Highlight 等返回 template.HTML,不会二次转义。
读完本章你应该能够
- 判断「我手上是什么、我要什么」,从而在 Markdownify / HTMLtoMarkdown / Plainify / Unmarshal / Remarshal / Jsonify 之间选对函数;
- 说清
template.HTML与string返回类型的差别,以及什么时候必须补safeHTML; - 在自定义代码块渲染钩子里用
transform.HighlightCodeBlock的.Wrapped与.Inner,并知道语言不被支持时的退路; - 用
transform.ToMath在构建期渲染公式,并知道throwOnError与try两种错误处理方式; - 用
transform.Unmarshal解析 YAML/JSON/TOML/XML/CSV,并知道 CSV 的targetType会改变表头语义; - 用
transform.PortableText把 Sanity 数据转成 Markdown,并知道模板直接造的切片类型会报错、需要过一次 JSON。
建议阅读顺序
- transform.Markdownify —— 最常用:把字符串里的 Markdown 渲染成 HTML。
- transform.Plainify / transform.HTMLToMarkdown —— 从 HTML 得到文本或 Markdown。
- transform.Unmarshal / transform.Remarshal / encoding.Jsonify —— 结构化数据的进出。
- transform.HTMLEscape / transform.HTMLUnescape / transform.XMLEscape —— 转义三兄弟,注意二次转义与
safeHTML。 - transform.Emojify —— 短代码替换。
- transform.Highlight / transform.HighlightCodeBlock / transform.CanHighlight —— 语法高亮。
- transform.ToMath —— 构建期渲染数学公式。
- transform.PortableText —— 从 Sanity 这类 CMS 取富文本。
本章内容
- transform.CanHighlight 报告给定语言是否支持语法高亮。 (今天)
- transform.Emojify 返回把 emoji 短代码替换为对应 emoji 字符后的给定字符串。 (今天)
- transform.Highlight 返回用语法高亮器渲染后的给定代码。 (今天)
- transform.HighlightCodeBlock 返回代码块渲染钩子上下文中收到的、已高亮的代码。 (今天)
- transform.HTMLEscape 返回把特殊字符替换为 HTML 实体后的给定字符串。 (今天)
- transform.HTMLToMarkdown 返回转换为 Markdown 后的给定 HTML。 (今天)
- transform.HTMLUnescape 返回把每个 HTML 实体替换为对应字符后的给定字符串。 (今天)
- transform.Markdownify 返回渲染为 HTML 后的给定 Markdown。 (今天)
- transform.Plainify 返回删除所有 HTML 标签后的字符串。 (今天)
- transform.PortableText 返回转换为 Markdown 后的给定 Portable Text。 (今天)
- transform.Remarshal 返回按指定格式序列化后的字符串,它由一串序列化数据或一个映射编组而成。 (今天)
- transform.ToMath 返回把用 LaTeX 语言书写的给定数学标记渲染为 HTML 后的结果。 (今天)
- transform.Unmarshal 返回从 CSV、JSON、TOML、YAML 或 XML 格式的序列化数据解析出的映射或数组。 (今天)
- transform.XMLEscape 返回删除不允许的字符后再转义为对应 XML 形式的给定字符串。 (今天)