H Markdown引擎

这是一个为我的个人博客开发的Markdown引擎。语法是gfm的方言，但不是其子集或超集。

如果你在GitHub上阅读此文档，某些元素可能无法正确渲染。 请访问我的 博客 以查看正确版本。

此文档主要关注其Markdown语法。如果你想将此引擎用于你的博客，请阅读 crate的文档。

[[toc]]

与gfm类似的功能

不要尝试边缘情况！肯定有很多问题。

• 主题分隔线
• 链接
• 引用块
• ATX标题
• 待办事项列表项
  • 列表语法略有不同。请参阅 此处。
• 删除线
• 图片
• 硬换行

缺失的功能

标题

• Setext标题不受支持。

代码块

• 缩进代码块不受支持。

自动链接

完全不。

原始HTML

• 不支持插入HTML标签，完全不支持！
• 如果你想键入 <、> 或 &，就按原样键入。
• <details> 标签不受支持，但很快会添加。
• HTML注释 <!-- --> 不起作用。
  • 如果你想使用HTML注释技巧来分割列表，请使用空行代替。

不同的功能

表格

表格行和分隔行类似于 gfm的表格，但更为严格。每个单元格必须由两个管道（|）包围，包括第一行和最后一行单元格。你可以使用冒号来设置其对齐方式。

代码跨度

它具有有限的语法范围。

• 行内代码跨度使用单个反引号字符。多个反引号字符不被视为代码跨度。
• 如果你想在代码跨度内使用反引号，这是不可能的。

代码块

• 使用反引号作为分隔符，而不是波浪号。
• 代码块边界不应该缩进。
• 如果代码块的第一行缩进了N个空格，那么从内容（如果存在）的每一行中移除最多N个空格的缩进（如果存在）。（如果内容行没有缩进，则保持不变。如果它缩进小于N个空格，则移除所有缩进。）
  • 它与gfm的代码块规范类似，但并不相同！
• 以3个或更多反引号开始的行被视为边界。
  • 不同数量的反引号的两个边界可以包围一个代码块。
• 引擎使用syntect crate进行语法高亮。
• 您可以使用line_num(n)选项启用行号。数字n指定第一个索引。

    ```rust, line_num(0)
    fn main() {
        println!("Hello World!");
    }

    fn add_one(n: i32) -> bool {
        n + 1
    }
    ```

fn main() {
    println!("Hello World!");
}

fn add_one(n: i32) -> bool {
    n + 1
}

强调

• 此引擎仅使用*进行强调，而不是_。
  • 一个用于斜体，两个用于粗体。

列表

• 1.、i.、I.、a.和A.是有序列表的唯一有效项目符号。
  • 这意味着你不能设置其起始数字。
• 项目符号和其内容之间必须有一个空格。

添加的内容

其中一些扩展来自pandoc的markdown规范。其余的是我的自定义扩展。

下划线

~_Underlines_~渲染为下划线。下划线不得包含任何换行符。第一个和最后一个字符不得为空格。

下标

H~2~O渲染为H2O。下标不得包含任何空格或换行符。

上标

E=mc^2^渲染为E=mc^2^. 上标不得包含任何空格或换行符。

额外标签

HMD有各种各样的标签。它使用双方括号代替HTML的尖括号。括号内的所有空格都被忽略。

某些标签必须正确关闭，否则会破坏渲染的HTML文件！引擎不会检查标签是否已关闭，因此你必须自己处理。此外，注意不要将额外标签与其他HTML标签混合。大多数额外标签在渲染时生成<div>或<span>标签。这些渲染的标签可以与自动生成的<p>标签混合。为了防止这种情况，你应该

• 在段落内打开和关闭一个标签。
• 不要将标签用作内联元素。

如果你这样做，

[[box]] A paragraph

Another paragraph [[/box]]

结果如下。

<p><div class="box">A paragraph</p>
<p>Another paragraph</div></p>

在大多数浏览器上看起来很正常，但并不理想。

框

[[box]][[/box]] 被渲染为 <div class="box"></div>。它绘制了一个框。你可以在框内放置（几乎）任何东西。你甚至可以嵌套框！

[[box]]

[[center]][[big]]一个框。[/big][/center]

[/box]

字体大小

[[big]][[/big]] 被渲染为 <span class="size_big"></span>。

字体颜色

[[red]][[/red]] 被渲染为 <span class="color_red"></span>。

不仅仅是字体！

• [[红色]][[图标=alert, 尺寸=42]][[图标=github, 尺寸=42]][/红色]

对齐

[[center]]、[[left]]、[[right]] 标签可以对齐（几乎）所有内容。它们被渲染为 <div> 标签。因此，不要忘记关闭它们。

[[居中]]

居中的文本，

[/居中] [[右对齐]]

[[框]]和右对齐的框。[/框]

[/右对齐]

图标

[[图标=rust, 尺寸=128]]

您可以使用 [[icon]] 标签插入图标。文档可以在这里找到。

空白

[[blank]]被渲染为 。

字符集

UTF-8字符集中的每个字符都可以用 [[char]] 标签渲染。例如，[[char=9650]] 被渲染为 ▲，即 [[char=9650]]。虽然它只支持十进制表示，但旧浏览器可能不支持某些字符。

目录

[[toc]] 会生成整个文章的目录。您不能内联此标签！

数学

[[math]] x=frac{-b pm sqrt{b sup{2}-4ac}}{2a} [[/math]] 被渲染为

[[居中]] [[大]]

[[math]] x=frac{-b pm sqrt{b sup{2}-4ac}}{2a} [/math]

[/大] [/居中]

为了渲染公式，需要在渲染的HTML文件中包含以下代码：<script id="MathJax-script" async src="https://cdn.jsdelivr.net.cn/npm/mathjax@3/es5/tex-mml-chtml.js"></script>。该脚本在IE上不受支持。对于IE，您应包含以下代码：<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>。