docs: update markdown-util

packages/markdown-util/src/__tests__/cjk.test.ts

@@ -41,6 +41,10 @@ describe('strong', () => {
   it('Render multiple strong', () => {
     expect(render('**真，**她**真**，她')).eq('<p><strong>真，</strong>她<strong>真</strong>，她</p>')
   })
+
+  it('Render with escaped asterisks', () => {
+    expect(render(`\*\*真，\*\*她`)).eq('<p><strong>真，</strong>她</p>').not.eq('<p>**真，**她</p>')
+  })
 })
 
 it('clearStrongAfterSpace', () => {

packages/markdown-util/src/cjk.ts

@@ -60,7 +60,8 @@ export function parseStrong(): Transform {
             }),
           } as Paragraph,
         ]
-      } else if (it.type === 'text') {
+      }
+      if (it.type === 'text') {
         const list = parseAndTransform((it as Text).value, STRONG_REGEXP)
         return list.map((it) => {
           if (it.match) {

packages/website/docs/lib/markdown-util.md

@@ -2,7 +2,9 @@
 
 markdown 封装工具，基于 mdast 提供所有在处理 markdown 中需要用到的函数。建议使用 [astexplorer](https://astexplorer.net/) 来查看 mdast 的结构。
 
-## fromMarkdown
+## 解析与输出
+
+### fromMarkdown
 
 将 markdown 转换为 mdast，支持自动解析 yaml 元数据。
 
@@ -17,7 +19,7 @@ const mdast = fromMarkdown(md)
 console.log(mdast)
 ```
 
-## toMarkdown
+### toMarkdown
 
 将 mdast 转换为 markdown。
 
@@ -42,7 +44,7 @@ const md = toMarkdown(mdast)
 console.log(md)
 ```
 
-## mdToHast
+### mdToHast
 
 将 mdast 转换为 hast，hast 是一种表示 html ast 的语法树，这个函数就是将 markdown 的语法树转换为 html 的语法树。
 
@@ -67,7 +69,7 @@ const hast = mdToHast(mdast)
 console.log(hast)
 ```
 
-## hastToHtml
+### hastToHtml
 
 将 hast 转换为 html。
 
@@ -95,7 +97,9 @@ const html = hastToHtml(hast)
 console.log(html)
 ```
 
-## visit
+## AST 实用函数
+
+### visit
 
 遍历 mdast，支持修改节点。
 
@@ -124,7 +128,7 @@ visit(mdast, (node) => {
 console.log(mdast)
 ```
 
-## getYamlMeta
+### getYamlMeta
 
 获取 mdast 中的 yaml 元数据。
 
@@ -153,7 +157,7 @@ const res = getYamlMeta(mdast)
 console.log(res) // { title: '标题' }
 ```
 
-## setYamlMeta
+### setYamlMeta
 
 设置 mdast 中的 yaml 元数据。
 
@@ -178,7 +182,7 @@ setYamlMeta(mdast, { title: '标题' })
 console.log(mdast)
 ```
 
-## flatMap
+### flatMap
 
 映射一棵 ast 树，可以删除或新增节点。
 
@@ -241,7 +245,7 @@ flatMap(mdast, (node) => {
 console.log(mdast)
 ```
 
-## select
+### select
 
 选择 mdast 中的节点
 
@@ -266,7 +270,7 @@ const res = select(mdast, 'heading')
 console.log(res)
 ```
 
-## selectAll
+### selectAll
 
 选择 mdast 中的所有节点
 
@@ -290,3 +294,57 @@ const mdast = {
 const res = selectAll(mdast, 'heading')
 console.log(res)
 ```
+
+## 其他
+
+### cjk
+
+支持目前 markdown 无法处理的中文，例如在使用强调时，你可能会遇到不生效的情况，下面是已知的一些情况。
+
+| example      | render     |
+| ------------ | ---------- |
+| `**真，**她` | **真，**她 |
+| `**真。**她` | **真。**她 |
+| `**真、**她` | **真、**她 |
+| `**真；**她` | **真；**她 |
+| `**真：**她` | **真：**她 |
+| `**真？**她` | **真？**她 |
+| `**真！**她` | **真！**她 |
+| `**真“**她`  | **真“**她  |
+| `**真”**她`  | **真”**她  |
+| `**真‘**她`  | **真‘**她  |
+| `**真’**她`  | **真’**她  |
+| `**真（**她` | **真（**她 |
+| `**真）**她` | **真）**她 |
+| `**真【**她` | **真【**她 |
+| `**真】**她` | **真】**她 |
+| `**真《**她` | **真《**她 |
+| `**真》**她` | **真》**她 |
+| `**真—**她`  | **真—**她  |
+| `**真～**她` | **真～**她 |
+| `**真…**她`  | **真…**她  |
+| `**真·**她`  | **真·**她  |
+| `**真〃**她` | **真〃**她 |
+| `**真-**她`  | **真-**她  |
+| `**真々**她` | **真々**她 |
+| `**真**她`   | **真**她   |
+
+有一些解决方法，但并不直观。例如添加额外的空格、避免将中文符号放在 `**` 前面、甚至是添加零宽度空格之类的。
+
+| example                      | render                     |
+| ---------------------------- | -------------------------- |
+| `**真，** 她`                | **真，** 她                |
+| `**真**，她`                 | **真**，她                 |
+| `**真，**​她` | **真，**​她 |
+
+目前 cjk 扩展函数主要从两个方面来支持
+
+1. 如果发现强调之后存在空格，则会清除。例如 `**真，** 她` 会被渲染为 `<p><strong>真，</strong>她</p>`
+2. 支持直接正确解析 `**真，**她`。会被渲染为 `<p><strong>真，</strong>她</p>`
+
+两者各有优缺点。
+
+1. 增加了额外的空格之后，可以在任何平台渲染，尽管会有额外的空格。
+2. 非常直观和符合直觉，但在其他平台不一定能正确渲染，例如 github。并且，这会破坏一些现有的渲染规则，例如 `\*\*真，\*\*她` 也会被渲染为 `<p><strong>真，</strong>她</p>`。
+
+目前针对 markdown 规范修改的 [相关 issue](https://github.com/commonmark/commonmark-spec/issues/650) 正在讨论中。