多年来,我每个工作日都会编写 Markdown - 插件 README、更改日志、文档 Toolz.dev、WP Adminify 的发布笔记,我提交消息的一半。而且大部分时间我都把渲染步骤当作魔法。你写星号,GitHub 显示粗体。很好。继续。
然后我构建了一个文档部分,将 Markdown 从数据库中删除,并将其渲染到 Next。js 页面中,魔法变成了我必须做出的非常具体的决定列表。单换行符是否成为 a <br>吗?(github评论说可以。markdown规范说不。)是 <div> 在源渲染为 div 或字面文本?(取决于谁在问,以及您是否信任作者。)什么类在围栏代码块上,所以荧光笔将其拾取?为什么一个解析器会转动 **bold**text 放进粗体,另一个就不管它了?
None of that is exotic。It is just the stuff nobody tell you, because Markdown looks so simple to people subsequence there is nothing under it。inter it is require much of the 降价到 HTML toolz。dev上的converter将这些决策暴露为交换机而不是隐藏它们,这是我在调试时想要的这个工具的版本,为什么我的换行符不断消失。
TL;博士: Markdown是一种写入格式;HTML是显示格式。有些东西必须编译一个到另一个。绊倒人的规则:连续的行加入到一个段落中,除非你用两个空格结束一行(或打开"breaks"选项),原始HTML要么通过,要么转义取决于解析器's信任设置,而GitHub's方言(GFM)在上面添加表,任务列表,删除线和裸URL自动链接 共同标记 基线。围栏代码编译为
<pre><code class="language-js">就是钩子棱镜,highlight。js 和 Shiki 寻找。 标记到 HTML 转换器 在您的浏览器中执行所有这些操作,每个开关都会暴露。
什么是 Markdown?为什么它需要转换?
Markdown是John Gruber在2004年发表的一种纯文本语法,其中有一个明确的设计目标:Markdown文档应该按原样发布,可读为纯文本,而看起来不像是用标签标记的,这就是为什么该语法借鉴了人们已经在电子邮件中使用的约定 - 强调单词周围的星号,标题下的一行破折号,a > 为报价。
Markdown 后果不是渲染格式,没有什么显示 Markdown,浏览器显示 HTML,以及你曾经拥有过的每一个地方 看见了 Markdown 渲染 - GitHub、静态站点、文档门户、聊天应用程序 - 首先运行解析器并将 HTML 放在屏幕上。
So转换就要发生在某处, 你的选项大致是:
- 在构建时间、静态站点生成器或捆绑程序中。当内容存放在您的存储库中时,罚款。
- 根据要求时间器(server)上。当内容来自数据库时是必要的,如果你在每个请求上都做,而不需要缓存,那么成本很高。
- 在浏览器中,在你需要的时刻,当"的答案时,你想要的是哪一个"我只需要html来做这一件事"是一个复制粘贴,而不是一个构建管道。
That third case比听起来更常见 将发布笔记粘贴到只需要HTML的CMS字段 将README放入电子邮件模板 在提交之前检查doc会是什么样子 将用黑曜石编写的草稿转换成可以交给设计师的东西 这些都不能证明将解析器连接到项目中是合理的。
CommonMark 和 X 之间的区别是什么,请问您是否需要使用 CommonMark 和 X 之间的区别是什么,请问您是否需要使用 CommonMark 和 CommonMark 的区别是什么 GitHub 口味的降价嗎?
Gruber's原始规格是一页散文和一个Perl脚本,它留下了足够的模糊性,以至于每个实现都在边缘情况下存在分歧。 共同标记 是答案:一个严格的、可测试的规范,具有数百个示例的一致性套件,这样两个符合要求的解析器对相同的输入产生相同的输出。它定义了基线 - 标题、段落、强调、链接、图像、列表、块引用、代码块、主题中断、反斜杠转义、HTML块。
GitHub 风味降价 (GFM) 是 CommonMark 的正式超集,由 GitHub 指定,它添加了人们一直要求的东西:
| 特点 | 共同标记 | GFM | 语法 |
|---|---|---|---|
| 表格 | 否 | 是的 | | a | b | 着一个 | --- | --- | 分隔行 |
| 任务列表 | 否 | 是的 | - [x] done / - [ ] todo |
| 走秀 | 否 | 是的 | ~~gone~~ |
| 自动链接裸露 URL | 否 | 是的 | https://toolz.dev 没有括号 |
| 脚注 | 否 | 是(GitHub 扩展) | [^1] |
| 标题、列表、代码、重点 | 是的 | 是的 | 相同的 |
如果您的 Markdown 来自 GitHub README、GitLab wiki、Notion 导出或大多数现代编辑器,那么它是 GFM。在转换器中打开 GFM,否则您的表将呈现为字面管道,这是排名第一的 "转换器坏了"支持问题任何发送这些工具的人都会收到。
为什么我的换行消失了?
Markdown因为按照纯文本邮件的约定, 将连续的非空行当成一个单段, 这:
Line one
Line two
生产 <p>Line one\nLine two</p>- 一段,当浏览器渲染时,换行符会崩溃到一个空间。它不是一个错误;它是规格,它的存在是为了让您可以在文本编辑器中的 80 列处硬包装您的散文,而不会将该包装泄漏到输出中。
获得实际休息的方法有三种:
- 一条空行 开始一个新的段落,这是你大部分时间想要的。
- 两个拖曳空间 1行末产生硬断-
<br />。这是标准的把戏,在你的编辑器里是看不见的,这就是为什么人们会觉得它令人抓狂。 - 反斜杠 在 CommonMark 中,行尾执行相同的操作,并且至少是可见的。
然后是第四条路,这是混乱的根源: 许多平台打开"破发"模式 每一条换行符都变成了一个 <br />。GitHub评论和问题这样做大多数聊天应用程序都是这样做的。GitHub README文件 不。因此,在 GitHub 问题和同一存储库的 README 中,相同的文本呈现方式有所不同,这确实是一个糟糕的设计,我们现在都陷入了困境。
Converster 将其暴露为交换机,如果您的源代码是为聊天风格的渲染器编写的,请打开行中断,如果是文档,请将其关闭,并像 spec 意图一样使用空行。
HTML 原始是如何处理的?
Markdown 允许内联 HTML - 原始规范明确表示您编写的任何 HTML 都会直接通过。这是您作为作者时的一项功能(您想要您的 <details> 块,你的 <img> 具有宽度属性,您的锚具有 rel的),而当你不是的时候,这是一种责任。
因为如果您启用 HTML 传递来渲染不受信任的 Markdown,则存在 XSS 漏洞。 <script>alert(document.cookie)</script> 是有效的markdown。也是如此 <img src=x onerror="...">.所以是一个 <a href="javascript:...">。 评论框、用户个人资料简介、公共 wiki(任何陌生人写下其他人读到的 Markdown 的地方)必须逃离 HTML 或使用真正的消毒器对输出进行消毒(DOMPurify 是通常的答案,它是真正的消毒器,正是因为正则表达式不足以进行敌对输入)。
该转换器默认为 逃跑 原始 HTML: <div> 在您的来源中显示为字面文本 <div> 在输出中,就像您所写的一样 <div>。源是你的时候可以开启直通,而且不管那个设置,直播预览条 <script>、 <style>,内联 on* 活动处理程序和 javascript: URLs之前渲染 - 深度防御措施,所以粘贴别人's README到预览窗格中无法执行他们的代码。那是预览安全措施,而不是通用消毒器:如果您正在构建一个渲染用户Markdown的产品,请使用专用的消毒器服务器端,并且不信任正则表达式,包括我的。
如果您需要逃脱角色 从 Markdown所以它呈现字面上 - 一个星号应该保留一个星号, 文件名中的下划线 - 反斜杠做: \*not emphasis\*。如果你正在向另一个方向争论实体, HTML 实体编码器/解码器 是那份工作的工具。
一个好的转换器实际上应该发出什么 HTML?
语义、无聊、无类的 HTML - 除一个例外。
- 标题变成了
<h1>,<h6>.启用标题 ID,每个也都会得到一个 slugifiedid的,当两个标题共享一个标题时去重复(#setup、#setup-1)。那是使#anchor深度链接有效,这就是目录生成器所悬而未决的。 - 带信息串的围栏块 -
```js- 成为<pre><code class="language-js">. *这是例外。** `语言-`类是惯例棱镜,highlight。js和shiki都在寻找,这就是为什么转换器会发出类。转换器不会为您的代码着色;页面上的荧光笔会为您的代码着色,并且需要那个钩子。 - 列表成为
<ul>/<ol>并且这里有一个值得了解的微妙之处:a 紧 列(项目之间没有空行)将文本直接放在里面<li>,而a 松动 列(项目之间的空行)包裹每个项目's内容中<p>。那是 CommonMark 行为,而不是怪癖,这就是为什么当你在两个子弹之间添加一条空行时,你的列表突然增加了垂直间距。 CSS 没有被破坏; HTML 真正改变了。 - 表格变得真实
<table>/<thead>/<tbody>标记,与style="text-align:center"当分隔符行使用时在单元格上:---:。 - 任务列表变成了
<input type="checkbox" disabled>里面<li>的,这正是 GitHub 发出的。
Content-first,没有包装器 div,没有实用程序类。您从外部对其进行风格设计,并带有 a .prose 类或您自己的规则,并且标记保持便携。
如何使用转换器?
第 1 步:粘贴标记
README、更改日志、发布说明、草稿中掉落。输入时输出更新 - 没有转换按钮,也没有上传任何内容。
步骤 2:设置开关
GitHub 风味 论来源是否有表格、任务列表或删除线(它可能确实如此)。 标题 ID 如果你想要主播就开启。 换行 仅当源代码是为聊天风格的渲染器编写的时。 允许原始 HTML 仅当来源是您的时才打开。 完整文件 如果您想要一个完整的 HTML5 页面,其中包含 doctype、字符集、视图端口和 a <title> 取自你的第一个 <h1>- 当您想直接在浏览器中打开结果或将其丢弃在静态主机上时非常有用。
3步:检查预览
切换到预览选项卡并确认结构。stats 行会告诉您单词、标题、链接、图像、代码块和阅读时间 - 查看帖子的方便之处在于您在发布帖子之前认为的长度。为了更彻底的计数, 字数计数器 对同一文本进行可读性和关键字密度。
4步:取输出
复制 HTML,下载为 .html 文件,或复制生成的目录 - 链接到每个标题锚的 Markdown 嵌套列表,准备粘贴回文档顶部。
如果您将结果粘贴到字节重要的页面中,请将其运行到 HTML 迷你器 afterwards。converter's输出为可读性缩进,而不是为导线缩进。
常见用例
将 README 访问网站
Plugin和包作者写一个好的README,那么就需要在一个登陆页面上同样的内容,README是带有表格和徽章的GFM;登陆页面需要HTML。用你现有的CSS转换,粘贴,样式。标题ID免费给你一个侧边栏TOC。
发布到仅接受 HTML 的 CMS
CMS字段、电子邮件平台和遗留管理面板很多都采用HTML,而没有其他任何东西,如果你在Markdown中起草- 而大多数定期写作的人都会这样做- 这就是桥接器与转换 完整文件 off,所以你得到片段而不是整个页面,然后将其粘贴到字段中。
对文档页面进行原型设计
Docs 站点中提交内容之前,在本地转换它会向您显示实际的标题层次结构以及您的代码栏是否带有正确的语言。An h3 那应该是一个 h2 TOC中是显而易见的,在源中是不可见的。
审核其他人撰写的内容
Paste a contributor's Markdown,看看发出的HTML,你马上就能看到他们是用真实的标题还是加粗了一行来伪造一个- 一种破坏文档结构和可访问性的习惯屏幕阅读器通过标题导航; **Big Text** 不是标题,它是一个粗体段落,转换器向您显示在一行输出中。
提取目录
Long docs需要一个,用手维护保证它不新鲜,从标题生成,粘贴进去,每当标题发生变化时就会再生。
高级:此解析器执行和不执行的操作
它是一个手写解析器,大约 400 行,没有依赖项 - 这是故意的,因为将 200KB 依赖项拉入整个点很快的页面的 Markdown 解析器是一笔糟糕的交易。
覆盖: ATX 标题 (# x) 和集合标题(下划线为 === / ---),段落,强调和强烈(*、 _、 **、 __)、带回退运行匹配的内联代码、带信息字符串的围栏代码、缩进代码块、带惰性延续的块引号、嵌套列表(有序和无序、紧密和松散)、主题中断、带标题的链接和图像、角括号自动链接、电子邮件自动链接、反斜杠转义和 GFM 集:带对齐的表格、任务列表、删除线、裸 URL 自动链接。
未涵盖: 参考风格的链接([text][ref] 着一个 [ref]: url definition ethere)、脚注、定义列表,以及一些真正晦涩难懂的围绕 HTML 的 CommonMark 角案例,阻止段落,如果您正在运行 CommonMark 一致性套件来对抗它,它不会获得 100% 的分数,如果您正在转换 README、更改日志或博客文章,您不会注意到。
这是一笔诚实的交易,也是转换器立即加载并与网络关闭配合的原因。对于需要精确的 CommonMark 一致性的内容管道,请使用 markdown-it、 remark 或 cmark 在你的建筑中;这就是他们的目的。
常问问题
如何将 Markdown 转换为 HTML？
Markdown粘贴到编辑器中,HTML立即出现 - 没有转换按钮,也没有文件上传如果您的源使用表格或任务列表,打开GitHub风味Markdown,然后复制HTML或下载为。html文件,所有内容都在您的浏览器中运行,因此未发布的草稿和内部文档永远不会离开您的设备。
什么是 GitHub 风味降价？
GitHub 调味标记(GFM)是 CommonMark 的正式指定超集,它添加了表格、任务列表复选框、带有双波浪号的删除线以及裸露 URL 的自动链接,它是 GitHub 用于渲染 README 文件和问题的方言,也是当今大多数 Markdown 编辑器默认在此转换器中启用的。
为什么我的单行断线消失了？
Standard Markdown 将连续的行连接成单个段落;只有在以两个空格结束行、使用尾随反斜杠或留下空行时,行间断才会保留。如果您希望每个换行符都成为 a <br />启用换行选项 - 这是 GitHub 注释和大多数聊天应用程序使用的行为,但这不是 README 文件所做的。
转换器是否突出显示我的代码?
它发出荧光笔所需的标记,但不会为代码本身着色。带有语言标记的围栏代码块 js 变成 <pre><code class="language-js">的,也就是类约定棱镜,highlight。js和shiki都寻找。将其中一个库添加到您粘贴输出的页面中,突出显示会自动出现。
我的降价中是否保留了原始html？
默认情况下它已转义,因此 <div> 以文字文本而非标签的形式出现。打开允许原始 HTML 选项,直接传递标签,这是当您的 Markdown 故意混合在 HTML 中时您想要的 - a <details> block,或者是带有属性的图片。只为你信任的源启用它,因为来自不受信任作者的原始html是一个xss向量。
粘贴我没有写的降价是否安全？
是的。HTML 默认情况下会转义,并且实时预览在渲染之前会额外删除脚本和样式标签、内联事件处理程序和 javascript: URL。您粘贴的任何内容都不会传输到任何地方。如果您正在构建一个从陌生人渲染 Markdown 的产品,仍然使用 DOMPurify 服务器端等专用消毒器 - 预览过滤器并不能替代它。
我可以从我的标题中生成一个目录吗？
是的。启用标题 ID 后,每个标题都会得到一个已弹化的、去复制的锚,并且该工具会构建一个链接到每个标题的 Markdown 目录。将其复制回文档顶部,链接针对生成的 ID 进行解析。每当您的标题发生变化时,就会重新生成它,而不是手动维护它。
该转换器是否完全实现 CommonMark?
它实现了人们实际编写的结构 - ATX 和 setext 标题、段落、强调、链接、图像、自动链接、块引号、嵌套和松散列表、围栏和缩进代码、主题中断、反斜杠转义 - 加上 GFM 扩展。参考样式的链接、脚注和一些罕见的 CommonMark HTML 块边缘情况不包括在内。为了在构建管道中保持位精确一致性,请使用 markdown-it、remark 或 cmark。
相关工具: 降价到 HTML · HTML 实体 · HTML 迷你器 · 字数计数器 · 蛞蝓发生器
相关阅读: Web开发人员's工具包 · 文本工具指南
