我也希望 Markdown 能够支持“内容引用/嵌入”

所谓内容引用1,就是用类似 C 语言中的 #include<> 宏语法把其它地方的内容插入到当前位置。

这种需求在编写表格的时候特别需要:如果表格的单元格内容一旦稍微复杂(比如多于一行),可读/可写/可维护性就是直线下降⬇️。之前还因此实现了类似维斯百科的复杂表格写法,但是效果不尽如我意。2

某些 Markdown 变种支持类似 [!INCLUDE] 的语法插入。但这还属于极端变种/方言,几乎没有其它实现了同样的做法。

刚刚在 StackOverflow 上看到别人有几乎和我完全一样的需求:html - How do I insert a referenced block of text in markdown? - Stack Overflow,所以想写篇随笔记录一下。

很早之前就想过写一个自己的 Markdown 扩展,调研如下:

  1. 考虑到 块引用(blockquote) 是个 Container Block,内部可以包含任意内容。所以,何不基于它来创建一个具名的块引用,然后在其它地方通过名字引用?
  2. 但是,块引用实际上使用 > 语法后面跟踪内容来描述内容,压根没地方插入这个“名字”。尽管可以模仿 Hugo 一样在最后插入形如 {key=value} 的参数/属性块3来到达类似目的,但是我觉得这并不是一个优雅的做法。至少在 CommonMark 标准接受这种做法以前我不太认同。

所以我想提供一种块引用的变体,不用 > 来表示,因为它:

  1. 写起来很麻烦,要对被引用内容的每一行都插入 >,如果编辑器没有块编辑功能,重复操作起来简直是恶梦;
  2. 如果块引用内有类似代码块的复杂缩进内容,这也会是灾难级的编辑体验;
  3. 当块引用内存在另外的块引用时(其又包含代码块时),那画面太美我不敢想像。

最初我想用 """name(见下面划线标记的行;类似 Python 的文档注释)来开启一个具名的块引用,此时渲染器默认不渲染,只被用作被其它地方引用的用途:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
"""name
This is a paragraph.

```go
func main() { }
```

这是一个列表:

* item1
* item2
"""

然后可以在其它地方用类似 """name""" 的方式引用它,引用后,即把上述复杂的内容插入到当前位置。

看起来挺优雅的,但是我没细想🤔。


  1. 这个名词是我自己创造的,我不知道别人怎么描述这个东西。 ^

  2. 这个东西的存在是为了支持 rowspancolspan、样式等内容,并不是为了能编辑复杂内容。见:movsb/goldmark-wiki-table ^

  3. Markdown attributes ^

碎碎念 开发笔记