链接语法

因为链接语法是 Markdown 引用文件的关键，它是 v-no 主要进行扩展的目标。

一个标准 Markdown 链接语法由三个部分组成：

1. !：标记它是一个文字链接还是图像链接。
2. [text]：
   • 对于文字链接，它被渲染成元素的 innerHTML。
   • 对于图像链接，它是元素的 alt 属性。
3. (path "title")：
   1. path：
      • 对于文字链接，它是元素的 href 属性。
      • 对于图像链接，它是元素的 src 属性。
   2. title：元素的 title 属性。

你可以发现，只有 title 的含义不会随链接的类型发生变化，而且似乎写 Markdown 时很少会用到它，这真是一个值得动刀子的好地方。

v-no 会截取 title 中最后出现的 # 符号和它后面的部分作为识别标记，而在它之前的部分会成为新的 title（如果它为空，链接不会有 title 属性）。对于不同类型的链接，标记也有不同的工作方式：

• 文字链接：如果 path 以 / 开头，并且指向 .md 文件（可以省略 index.md），则将它转换为以 # 开头的 Hash 地址。
  • 如果 # 之后还有更多内容，以 ? 作为分隔，在它之前的部分会组成锚点，之后的部分则是查询字符串。
  • 如果 text 为空，用 path 指向文件的标题填充它。如果它还单独位于一个 <li> 中，则将这个 <li> 转换为一个展示文件部分元数据的特殊列表项。
• 图像链接：# 之后的部分用于控制它的样式。
  1. 如果它是数字，则作为图像的宽度。
  2. 如果它以 . 开头，将它加到 class 属性，你可以用 . 分隔多个值。有几个特殊的 class 值：
     • hidden：隐藏图像。
     • left、right：将图像浮动在左右两侧。
     • 如果它是以 w 开头的一组数字，则将数字部分作为图像的宽度。
  3. 其它情况都会直接把它填进 style 属性。

title 写多了还是有点麻烦。v-no 还有几个会替换 / 移除原链接的标记，它们选择对 text 进行扩展，并且都需要单独占据一行使用。

• 嵌入链接：用于引入嵌入文件。text 需要以 + 开头，它可以跟一个 #，在它之后的部分会被解析成参数对象。各个参数项之间要用 | 分隔，它们会依序得到一个从 0 开始的序号。你也可以用赋值语句（a=1）标记一个命名参数，让它除了序号还拥有一个字符串别名。
• 自定义脚本链接：path 要以 .js 结尾，text 只能包含 $，不过不限个数。使用多于一个 $ 会将它标记为一个驻留脚本。
• 自定义样式链接：除了要以 .css 结尾、使用 * 作为标记，其它地方和自定义脚本类似。

嵌入文件

嵌入文件就是由嵌入链接引入的文件，它会替代链接字符串进行渲染。

你可以用它将一个大文件分成几个小文件，也可以用来创建会多次使用的片段文件。如果嵌入链接和标题标记（二至六级）配合使用，它就会成为一个能自适应嵌入标题层级的块嵌入（嵌入文件的标题为块标题，在它下面的标题会自动降级）。它还支持通过嵌入链接语法传递参数，因此也具有模板的功能。

嵌入参数

嵌入参数使用 Mustache 语法（{{ }}）占位，它有序号（从 0 开始）和字符串两种索引方式（{{ 0 }} 或 {{ a }}），字符串（命名）参数也可以用对应序号索引，用 | 分开的部分会作为索引值为 undefined 时的默认值（{\{ 0| }}，转义了 { 以避免被替换）。

文件切片

文件切片标记会将文件内容划分为多个切片，你可以通过传入命名参数 slice 来指定需要嵌入的切片序号（从 0 开始，如果为 random 则随机选取）或命名字符串（和嵌入参数类似），没有这个参数文件就不会被切分。

嵌入参数的执行优先级最高，然后是文件切片，最后才是行内脚本，这意味着你可以将传入的参数作为脚本代码的一部分执行。

details 语法

details 语法是用 ::: 包围的块级语法，它可以帮助你生成 <details> 标签。

它的第一行由三部分组成：

• open：是否默认展开，可以省略。
• class 列表：以 . 开头，用 . 相连，可以省略。有几个特殊 class：
  • readonly：禁用 <summary> 的点击事件。
  • empty：不显示 <summary>，默认展开。
  • bold：<summary> 的字体为粗体。
  • 主题色：
    • success：绿。
    • warning：黄。
    • danger：红。
    • dark：黑。
• <summary> 标签的 innerHTML：支持 Markdown 语法，可以省略（不过因为它的优先级最高，如果你需要使用前两项，就不能省略它。你要是不需要渲染它，就敲一个反斜杠 \）。

示例

::: summary
content
:::

::: .readonly summary
content
:::

::: .readonly.bold summary
content
:::

::: open summary
content
:::

::: open .readonly summary
content
:::

::: .empty summary
content
:::

:::
content
:::

::: open .success summary
content
:::

::: open .warning summary
content
:::

::: open .danger summary
content
:::

::: open .dark summary
content
:::

::: .success.empty summary
content
:::

::: .warning.empty summary
content
:::

::: .danger.empty summary
content
:::

::: .dark.empty summary
content
:::

dl 语法

dl 语法是以 : 开头的块级语法，它可以帮助你生成 <dl> 标签。

它通常需要单独占据一行，不过也能用在引用语法 > 的后面。它可以单独或连续使用，也可以和它上一行的文本或图像组成一个语法块。

示例

: 单独使用

单独使用

: 连续使用
: 连续使用
: 连续使用

连续使用

连续使用

连续使用

文本。
: 作为文本的说明。

文本。

作为文本的说明。

![](/uploads/images/logo.png)
: 作为图像的说明。

作为图像的说明。

> 文本
> : 作为引用文本的说明

文本

作为引用文本的说明

折叠标题

v-no 渲染的页面标题除了会带有锚点图标（右侧），还有一个指示标题层级的元素（左侧），点击它就可以折叠归属于这个标题下的所有元素，不过只对 <article> 的直接子元素有效。

你可以在标题标记和文本之间添加一个加号（## + heading）来默认折叠指定标题。

就像下面这样：

heading 2-1

paragraph

heading 3-1

paragraph

heading 4-1

paragraph

heading 5-1

paragraph

heading 6-1

paragraph

heading 6-2

paragraph

heading 5-2

paragraph

heading 4-2

paragraph

heading 3-2

heading 2-2

paragraph

heading 3-1

paragraph

heading 3-2

paragraph

行内脚本

你可以通过编写可执行的行内代码，在一定程度上编程控制页面内容的展示。

行内脚本使用一对 $$ 作为标记，所有被它们包裹的字符串都会被放进下面这个独立的函数上下文中被 eval：

(function(path, title, data, isSnippet) {
  // 行内脚本})(path, title, data, isSnippet)

• path：执行时的文件路径。
• title：执行时的文件标题。
• data：执行时的文件内容。
• isSnippet：是否执行在嵌入文件中。

因此，你至少需要一条 return 语句才能得到有效的输出结果，它会作为 Markdown 文件的一部分被渲染。

为一行代码写一堆 return 也挺麻烦，为了简化输入，v-no 会将字符串开头的 : 替换为 return 、:: 替换为 return vno.。如果你使用三个冒号 ::: ，在它之后的字符串会构成 return vno.getMessage() 的 getMessage 函数实参。

你可以认为你能在浏览器控制台下执行的代码，对它来说也是同样有效的。只不过同步脚本会在文件渲染之前执行完毕，这意味着它查询不到渲染后的页面元素，而这个问题可以用异步脚本解决（见最后一个示例）。

没错，v-no 支持在行内脚本中等待异步函数，含有 await 的字符串都会被包进上面那个函数的异步版本中。这让它可以游离在渲染过程之外，做完事再回来更新页面。不过这也意味着浏览器需要支持 ES2017 的 async / await 关键字，它做不了任何转译。

最后需要注意一点，行内脚本的执行优先级通常是最高的。不过在嵌入文件中，它排在了参数传递和文件切分的后面，以便于你将传入的参数作为脚本代码的一部分。另外它也排在 Flags 和 [noCommon] 标记后，其它语法标记前。

示例

This page is open source, improve it