文档章节

转换函数

用这些函数把取值从一种格式转换为另一种格式。

这一章把「一种表示」变成「另一种表示」: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。

建议阅读顺序

  1. transform.Markdownify —— 最常用:把字符串里的 Markdown 渲染成 HTML。
  2. transform.Plainify / transform.HTMLToMarkdown —— 从 HTML 得到文本或 Markdown。
  3. transform.Unmarshal / transform.Remarshal / encoding.Jsonify —— 结构化数据的进出。
  4. transform.HTMLEscape / transform.HTMLUnescape / transform.XMLEscape —— 转义三兄弟,注意二次转义与 safeHTML。
  5. transform.Emojify —— 短代码替换。
  6. transform.Highlight / transform.HighlightCodeBlock / transform.CanHighlight —— 语法高亮。
  7. transform.ToMath —— 构建期渲染数学公式。
  8. 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 形式的给定字符串。 (今天)