简要总结
Markdown Formatting
这页说明书在讲一个叫“Markdown格式转换”的小工具是怎么工作的。你可以把它想成一个“翻译官”，它能把一种叫Markdown的、带简单符号的文字，变成不同聊天软件（比如Slack、Telegram、Signal）能看懂的漂亮样子。它先会把所有文字变成一种中间格式（就像画了一张设计图），然后再根据每个软件的要求，把设计图变成它们喜欢的最终样子。这样，不管你在哪里发消息，格式都不会乱掉。如果你想知道你的消息是怎么变成不同样子的，或者想自己动手让一个新软件也能看懂这种格式，就可以看看这页。
五岁小孩版解释
这个工具就像一个聪明的格式小帮手。它的工作是把用Markdown写的文字（就是那种用**表示加粗、用[]()表示链接的文字），变成各种聊天软件喜欢的样子。它不会直接变，而是先画一张“设计图”，这张设计图记下了所有文字和它们应该有的格式（比如哪里要加粗，哪里是链接）。然后，它再看着这张设计图，给每个软件做出它们专属的漂亮消息。
这个小帮手有三个主要目标。第一是一致性，意思是它只画一次设计图，就能给好多不同的软件用。第二是安全分块，意思是如果一条消息太长需要切成几段，它会在画好设计图后就切好，保证加粗、链接这些格式不会被切坏。第三是适配不同软件，意思是它能用同一张设计图，做出适合Slack、Telegram、Signal各自格式的消息。
它的工作流水线分三步走：
- 第一步：画设计图（把Markdown变成IR）。IR就是那张“设计图”，它记下了所有纯文字，还有哪些地方要加粗、变斜体、加删除线、变成代码块或者隐藏起来（这叫“剧透”），以及哪些文字是链接。这里要小心，为了和Signal软件配合，它数文字位置的方式有点特别（用UTF-16单位）。另外，表格只有在某个软件说“我要”的时候，才会被画进设计图里。
- 第二步：按需要切分设计图。如果消息太长了，就在这张设计图上把它切成几小块。这样切能保证加粗、链接这些“小装饰”完整地留在每一小块里，不会从中间断开。
- 第三步：给每个软件做最终消息。拿着切好的设计图小块，给每个软件做出它们能看懂的样子：
- 给Slack做，会用
*粗体*、_斜体_这样的符号，链接会变成<网址|标签>的样子。 - 给Telegram做，会用
<b>粗体</b>、<a href="网址">标签</a>这样的HTML标签。 - 给Signal做，会告诉它“从第几个字到第几个字要加粗”，链接如果标签和网址不一样，会变成
标签 (网址)的样子。
- 给Slack做，会用
关于链接，每个软件的处理方式也不一样：
- Slack：会把
[标签](网址)变成<网址|标签>，单独的网址就还是网址。 - Telegram：会把
[标签](网址)变成<a href="网址">标签</a>。 - Signal：会把
[标签](网址)变成标签 (网址)，除非标签和网址一模一样。
关于表格，因为不是所有软件都支持，所以你可以通过设置markdown.tables来告诉工具怎么处理：
code：把表格变成代码块（这是大部分软件的默认做法）。bullets：把表格每一行变成带圆点的列表（这是Signal和WhatsApp的默认做法）。off：不处理表格，直接发原始文字。
关于“剧透”（用||包起来的文字），目前只有Signal软件能真正把它藏起来，其他软件会直接把它当普通文字显示。
如果你想教这个工具认识一个新的聊天软件，可以按照下面的步骤来：
- 画一次设计图：使用一个叫
markdownToIR(...)的小工具来画设计图。 - 做最终消息：写一个小程序，用
renderMarkdownWithMarkers(...)和一张“样式对应表”，把设计图变成新软件能看懂的样子。 - 先切分，再制作：在制作最终消息前，先用
chunkMarkdownIR(...)把设计图切好，然后为每一小块做消息。 - 连接起来：更新新软件的发送程序，让它使用新的切分和制作工具。
- 测试一下：增加一些格式测试，如果这个新软件也会切分消息，还要加一个完整的发送测试。
最后，有一些需要小心的地方：
- 对于Slack，像
<@U123>、<#C123>这样的特殊符号必须原样保留，不能弄坏。 - 对于Telegram，要小心处理HTML标签外面的文字，别让它们把标签弄乱。
- 对于Signal，计算加粗范围时一定要用前面说的那种特别数数方式（UTF-16偏移量），不能用别的方法。
- 代码块（用```包起来的）后面要保留一个空行，这样每个软件才能正确显示它。