Markdown 元数据格式

Posted 2023-02-16

【中文标题】Markdown 元数据格式

【英文标题】：Markdown metadata format

【发布时间】：2017-10-28 04:37:57

【问题描述】：

是否有在 Markdown 格式的帖子中嵌入元数据的标准或约定，例如发布日期或帖子作者以供渲染器进行条件渲染？

看起来可能是这种Yaml metadata 格式。

有各种各样的策略，例如随附文件mypost.meta.edn，但我希望将其全部保存在一个文件中。

【参考方案1】：

有两种常见的格式看起来非常相似，但实际上在某些非常具体的方面有所不同。第三个非常不同。

YAML 前言

Jekyll 静态站点生成器普及了由YAML section markers 分隔的 YAML 前端。是的，破折号实际上是 YAML 语法的一部分。元数据是使用任何有效的 YAML 语法定义的。这是来自Jekyll docs 的示例：

---
layout: post
title: Blogging Like a Hacker
---

请注意，YAML 前端内容不会被 Markdown 解析器解析，但会在 Jekyll（或您正在使用的任何工具）解析之前被删除，并且实际上可用于请求与默认 Markdown 解析器不同的解析器页面（我不记得 Jekyll 是否这样做，但我见过一些工具）。

MultiMarkdown 元数据

更老更简单的MultiMarkdown Metadata 实际上被合并到一些 Markdown 解析器中。虽然它最近已更新为可选地支持 YAML 分隔符，但传统上，元数据结束并且 Markdown 文档从第一个空白行开始（如果第一行为空白，则没有元数据）。虽然语法看起来与 YAML 非常相似，但仅支持键值对，没有隐含类型。这是 MultiMarkdown 文档中的一个示例：

Title:    A Sample MultiMarkdown Document  
Author:   Fletcher T. Penney  
Date:     February 9, 2011  
Comment:  This is a comment intended to demonstrate  
          metadata that spans multiple lines, yet  
          is treated as a single value.  
CSS:      http://example.com/standard.css

MultiMarkdown 解析器包含许多该解析器独有的附加选项，但键值元数据用于多个解析器。不幸的是，我从未见过任何两个行为完全相同。如果没有定义这种格式的 Markdown 规则，每个人都会做出自己略微不同的解释，从而导致变化很大。

更常见的一件事是对 YAML 分隔符和基本键值定义的支持。

Pandoc 标题栏

为了完整起见，还有Pandoc Title Block。 If 具有非常不同的语法，并且不容易与其他两个混淆。据我所知，它仅受 Pandoc 支持（如果启用），并且仅支持三种类型的数据：标题、作者和日期。这是 Pandoc 文档中的一个示例：

% title
% author(s) (separated by semicolons)
% date

请注意，Pandoc 标题块是 Pandoc 支持的两种样式之一。如上所述，Pandoc 还支持YAML Metadata。

【讨论】：

Pandoc title block 中的自问链接是怎么回事？此外，%title 等示例不适用于我。

@isomorphismes 感谢您指出损坏的链接，现已修复。另外，我添加了一些说明。您需要显式启用 Pandoc 扩展才能使其工作。

补充说明：Hexo supports JSON front matter as well as YAML.

@КонстантинВан JSON 是有效的 YAML。因此，任何支持 YAML（并使用完整的 YAML 解析器）的实现也支持 JSON。

@Waylan 是的，这是我今年学到的。那时我不知道。

【参考方案2】：

解决方法使用标准语法并与所有其他查看器兼容。

我还在寻找一种将应用程序特定元数据添加到 Markdown 文件的方法，同时确保现有的查看器（例如 vscode 和 github 页面）将忽略添加的元数据。另外使用扩展的 markdown 语法也不是一个好主意，因为我想确保我的文件可以在不同的查看器上正确呈现。

所以这是我的解决方案：在 markdown 文件的开头，使用以下语法添加元数据：

[_元数据_：作者]：-“daveying” [_metadata_:tags]:- “降价元数据”

这是link references 的标准语法，当您的应用程序可以提取这些数据时，它们不会被渲染。

: 之后的- 只是 url 的占位符，我不使用 url 作为值，因为 url 中不能有空格，但我有场景需要数组值。

【讨论】：

我最喜欢这个 - 全面工作 - 并且是自我描述的。

100% 保持在降价空间内是一大优势。

【参考方案3】：

大多数 Markdown 渲染器似乎支持文件顶部元数据的这种 YAML 格式：

---
layout: post
published-on: 1 January 2000
title: Blogging Like a Boss
---

Content goes here.

【讨论】：

谢谢，这对我有用，在 VS Code 中有 Pandoc 扩展。

【参考方案4】：

正确。

使用 yaml 前端键值语法——就像 MultiMarkdown 支持的那样——但（ab）使用官方 Markdown URL 语法来添加你的元数据。

…我的解决方法如下所示：

---
[//]: # (Title: My Awesome Title)
[//]: # (Author: Alan Smithee)
[//]: # (Date: 2018-04-27)
[//]: # (Comment: This is my awesome comment. Oh yah.) 
[//]: # (Tags: #foo, #bar)  
[//]: # (CSS: https://path-to-css)  
---

将此块放在您的 .md 文档的顶部，文档顶部和第一个 --- 之间没有空行。

当您呈现为 html 等时，您的假 yaml 将不会被包含在内……它只会出现在 .md 中。

您也可以使用此技术在 Markdown 文档的正文中添加 cmets。

【讨论】：

这是@DavidDa 答案的变体，使用降价参考链接。我喜欢混合使用这两种语法：[:author]: # "JohnDoe".

@v.nivuahc 你的解决方案更简单，我喜欢 :)

【参考方案5】：

我为 Markdown 找到的最一致的元数据形式实际上是 HTML 元标记，因为大多数 Markdown 解释器都识别 HTML 标记并且不会呈现元标记，这意味着元数据可以以一种不会显示的方式存储在呈现的 HTML 中。

<title>Hello World</title>
<meta name="description" content="The quick brown fox jumped over the lazy dog.">
<meta name="author" content="John Smith">

## Heading
Markdown content begins here

您可以在 GitHub Gist 或 StackEdit 之类的地方尝试一下。

【参考方案6】：

这不是标准方式，但适用于 Markdown Extra。

我想要在解析器中工作的东西，但当我在存储文件的 Bitbucket 上浏览文件时也不会留下任何混乱。

所以我使用 Markdown Extra 语法中的Abbreviations。

*[blog-date]: 2018-04-27
*[blog-tags]: foo,bar

然后我用正则表达式解析它们：

 ^\*\[blog-date\]:\s*(.+)\s*$

只要我不在文中写出确切的关键字，它们就不会留下任何痕迹。所以使用一些足够隐蔽的前缀来隐藏它们。

【参考方案7】：

我没有看到这里其他地方或讨论该主题的各种博客中提到过这一点，但在我个人网站的一个项目中，我决定在每个降价文件的顶部使用一个简单的 JSON 对象来存储元数据。与上面的一些文本格式相比，它的输入有点麻烦，但它非常容易解析。基本上我只是做一个正则表达式，如^\s*(.*?)\s*(.*)$（使用s选项将.视为\n）来捕获json和markdown内容，然后用语言的标准方法解析json。它允许非常容易地使用任意元字段。