文档章节

Output format 方法

在 OutputFormat 对象上使用这些方法。

这一页解决什么问题

模板里只要出现「同一份内容还要以另一种形式发布」——RSS feed、JSON 索引、纯文本出口——就会用到 output format(输出格式)。渲染 RSS 自动发现的 <link> 标签、给页面加 rel="canonical"、判断某份输出叫什么名字、是什么媒体类型,靠的都是 OutputFormat 对象上的这几个方法。

上游这几页原来是「签名 + 一句话 + 一个小例子」,本站为每页补上了「什么时候用 / 什么时候别用」「一个可直接粘贴的实测示例」与「返回值边界(空值、取不到、类型不符)」三部分。

读完本章你应该能够

  • 先用 OutputFormats.Get 或 OutputFormats.Canonical 拿到一个 OutputFormat 对象,再调用本章的方法;
  • 分清 Permalink(含协议与域名的绝对地址)与 RelPermalink(根相对地址),并知道站点部署在子路径时两者都会带上子路径;
  • 用 Rel 加 MediaType 拼出正确的 <link rel=… type=… href=…>;
  • 知道 Get 取不到时得到的是空值:with/if 判为假,各方法返回空串,不报错——所以漏写判断的模板会静默生成 href=""。

建议阅读顺序

  1. 先拿到对象:methods/page/outputformats(Get、Canonical);
  2. 再取地址:Permalink → RelPermalink;
  3. 补齐 link 元素的另外两个属性:Rel → MediaType;
  4. 名字与配置对照:Name。

输出格式本身怎么配置([outputFormats]、[outputs]、[mediaTypes])见输出格式。

本章内容

  • MediaType 返回给定输出格式的媒体类型。 (今天)
  • Name 返回给定输出格式的标识符。 (今天)
  • Permalink 返回当前输出格式所生成页面的永久链接。 (今天)
  • Rel 返回给定输出格式的 rel 值,可以是默认值,也可以是项目配置中定义的值。 (今天)
  • RelPermalink 返回当前输出格式所生成页面的相对永久链接。 (今天)