怎么用 : Markdown 转 HTML
您文中所有的 HTML 符号一律转义,没有例外:写在 Markdown 里的一段脚本,出来是看得见的文字,永远不会变成可执行的东西。这比规范更严,而对一件产出“会被人打开的文件”的工具来说,这是唯一稳妥的做法。
这件工具许下的诺言不大,而且明写着:Markdown 的参考规范里有五百多个一致性示例。我们没有实现五百个。我们实现的是人们真正会写的那一部分,而这个页面把它逐条列出来,好让您在粘贴之前就知道哪些会被转换、哪些不会。
关于安全,有一处值得说准的立场问题。规范是允许在 Markdown 文档里写原始 HTML 的,而我们在它的正文里核对过:它没有在任何地方要求实现方去净化自己的输出;“请把结果过一遍净化器”这句话来自某些库的文档,不是来自规范。所以我们不会把它安到规范头上。
我们的选择更简单也更严:您文中所有的 HTML 符号一律转义。写在您 Markdown 里的一个标签,在结果中会以看得见的样子出现,绝不会生效。而危险的链接地址会被逐个点名拒绝,链接文字保留成纯文本并在屏幕上告知,这符合“地址属性里只允许 http 和 https”这条公开建议。
怎么用
- 把您的 Markdown 粘进来。它不会离开您的设备。
- 如果您要的是一个独立的 HTML 文件、而不是一段插进别处的片段,就把“完整页面”勾上。
- 把结果复制走或者下载下来。如果有地址被拒,表格里会点名。
支持的格式
会被转换的范围:井号标题和下划线式标题、段落、粗体、斜体、删除线、行内代码、带语言标注的围栏代码块、无序和有序列表、可嵌套的引用、水平分割线、带标题的链接和图片,以及行末两个空格构成的硬换行。表格、脚注和定义列表不转换:它们不属于基础规范。
Markdown 格式的文字
最多 200000 个符号。结果输出为 HTML,可以是片段,也可以是独立页面。
它的限制
只实现规范的一个子集,上面列着
参考规范里有五百多个一致性示例,其中不少覆盖的是根本没人会写的情形:带续行的四层嵌套列表、定义在后文的链接引用、数字型 HTML 实体。把五百个情形实现出来并逐一验证,那是一个独立的项目。我们宁可把哪些能用说清楚:这是一句更小的承诺,但它兑现得了。
写在您 Markdown 里的 HTML 一律转义,绝不照搬
规范是允许的,但一件产出“会被人打开的 HTML 文件”的工具,必须选稳妥这一边:塞在别人发来的 Markdown 里的一段脚本是会跑起来的。所以所有 HTML 符号都会变成看得见的文字。有一个后果得知道:如果您本来是有意用某个标签来做某种效果,它会在结果里原样显示出来,而这是有意为之。
只保留 http、https、mailto 开头的地址和相对地址
Markdown 链接可以带任何一种地址方案,包括那些一点就执行代码的。OWASP 关于页面注入脚本的公开建议说,地址属性里只应允许 http 和 https。工具照这条规则来,保留链接的文字,并在一张表里点名被拒的地址:一声不响地把它去掉,会让您误以为这个链接还能用。
表格不转换
用竖线写表格的语法流传很广,但它不属于基础规范:各家实现处理起来都有点出入,尤其在对齐和空单元格上。与其给出一个跟您平常那个平台不一样的表格,我们宁可不实现它。
关于这个工具的问题
我的文字会被发到什么地方吗?
不会。三十秒就能验证:按 F12 打开开发者工具,切到“网络”标签页,清空列表,然后把 Markdown 粘进来转换一次。一行都不会冒出来。把网断掉再做一遍:解析器就写在这个页面里。
为什么我的 HTML 标签在结果里原样显示出来了?
因为您文中所有的 HTML 符号一律转义,没有例外。Markdown 规范是允许原始 HTML 的,但一件产出“会被别人打开的文件”的工具,不能把一段来自它没写过的文本里的标签照搬过去:塞在收到的文档里的一段脚本是会跑起来的。如果您确实需要某个标签,请在转换之后到您的编辑器里加上,心里有数地做这件事。
我有一个链接点不了了。
那是因为它的地址用了一种点击时可以执行代码的方案。工具保留链接的文字,去掉地址,并在一张表里点名。如果这个链接来自一份不是您自己写的文档,那这条信息值得认真对待。会被保留的地址是 http、https、mailto、页内锚点和相对地址。
我的表格没有被转换。
没有,而这写在限制里。用竖线写表格的语法流传很广,却不在基础规范里,而且各家实现在对齐和空单元格上的处理都不一样。给出一个跟您平常那个平台长得不像的表格,比坦白说我们不做要更糟。
结果符合规范吗?
在我们写明的那个子集上,它遵守规范的规则,包括那些常被忘掉的:行末两个空格构成的硬换行、行内代码保护其内容不受任何其他解释、引用可以嵌套。除此之外,我们什么都不声称:规范里有五百多个一致性示例,我们没有把它们全都跑过。正因如此,页面上方写的是一张“哪些能用”的清单,而不是一枚合规徽章。