[gem-book] Refactor live update

.prettierrc.json

@@ -3,5 +3,13 @@
   "trailingComma": "all",
   "singleQuote": true,
   "printWidth": 120,
-  "endOfLine": "lf"
-}
+  "endOfLine": "lf",
+  "overrides": [
+    {
+      "files": ["*.md"],
+      "options": {
+        "printWidth": 80
+      }
+    }
+  ]
+}

packages/duoyun-ui/docs/en/02-elements/coach-mark.md

@@ -45,7 +45,10 @@ const items = [
 ];
 
 render(
-  html`<dy-side-navigation style="width: 50%" .items=${items}></dy-side-navigation>`,
+  html`<dy-side-navigation
+    style="width: 50%"
+    .items=${items}
+  ></dy-side-navigation>`,
   document.getElementById('root'),
 );
 ```

packages/duoyun-ui/docs/en/02-elements/popover.md

@@ -15,7 +15,9 @@ render(
     <dy-popover
       trigger="click"
       .content=${html`
-        <div style="width: 200px; height: 100px; display: flex; place-items: center; place-content: center;">
+        <div
+          style="width: 200px; height: 100px; display: flex; place-items: center; place-content: center;"
+        >
           ${new Date().toLocaleString()}
         </div>
       `}

packages/duoyun-ui/docs/zh/02-elements/coach-mark.md

@@ -45,7 +45,10 @@ const items = [
 ];
 
 render(
-  html`<dy-side-navigation style="width: 50%" .items=${items}></dy-side-navigation>`,
+  html`<dy-side-navigation
+    style="width: 50%"
+    .items=${items}
+  ></dy-side-navigation>`,
   document.getElementById('root'),
 );
 ```

packages/duoyun-ui/docs/zh/02-elements/popover.md

@@ -15,7 +15,9 @@ render(
     <dy-popover
       trigger="click"
       .content=${html`
-        <div style="width: 200px; height: 100px; display: flex; place-items: center; place-content: center;">
+        <div
+          style="width: 200px; height: 100px; display: flex; place-items: center; place-content: center;"
+        >
           ${new Date().toLocaleString()}
         </div>
       `}

packages/gem-book/docs/en/002-guide/004-metadata.md

@@ -34,7 +34,7 @@ redirect: ./new.md
 > [!WARNING]
 > Specifying redirection for folders is not supported
 
-## Folder
+## Folder {#dir}
 
 Folders sometimes need to specify a name (e.g: [i18n](./002-i18n.md)) and a display method in the sidebar/navigation bar. You can add `config.yml` to the folder, for example:
 

packages/gem-book/docs/en/002-guide/007-extension.md

@@ -119,7 +119,11 @@ Some plugin need to be used with slots, such as the built-in plugin `<gbp-commen
 
 ```html
 <gem-book>
-  <gbp-comment slot="main-after" client-id="xxx" client-secret="xxx"></gbp-comment>
+  <gbp-comment
+    slot="main-after"
+    client-id="xxx"
+    client-secret="xxx"
+  ></gbp-comment>
 </gem-book>
 ```
 

packages/gem-book/docs/zh/002-guide/001-sort.md

@@ -22,4 +22,7 @@ src/docs/
 └── <about.me 一级标题>
 ```
 
+> [!TIP]
+> 用文件名进行排序的好处是你能在 IDE 中预览排序后的结果，可以使用 [`--reverse`](./004-metadata.md#dir) 进行降序显示侧边栏
+
 默认情况下，这个数字不会显示在 URL 中，如果你的文件名本来就有相同格式的前缀，可以使用 [`displayRank`](./003-cli.md#--display-rank) 选项显示它们。

packages/gem-book/docs/zh/002-guide/003-cli.md

@@ -6,7 +6,7 @@ npx gem-book -h
 
 ## 配置文件
 
-`gem-book` 命令会自动从项目根目录查找配置文件 `gem-book.cli.json`，支持大部分命令行选项（同时提供时覆盖命令行选项），例如:
+`gem-book` 命令会自动从项目根目录查找配置文件 `gem-book.cli.json`，支持大部分命令行选项（同时提供时合并命令行选项），例如:
 
 <gbp-raw src="/gem-book.cli.json"><gbp-raw>
 
@@ -22,31 +22,28 @@ npx gem-book -h
 
 #### `-o, --output <path>`
 
-指定输出文件目录，默认为指定的文档目录；如果是 `json` 文件路径则作为 `gem-book.json` 的输出路径。
+指定输出文件目录，默认为指定的文档目录；如果是 `json` 文件路径则只输出 [`json`](#--json) 文件。
 
-#### `-d, --source-dir <dir>`
+#### `--github <url>`
 
-指定文档目录在 GitHub 中的位置，最终生成前往 GitHub 的链接，默认使用当前命令指定目录。
+指定 GitHub 地址，会渲染到导航栏中，默认会从 `package.json` 和本地 `.git` 目录中读取。
 
 #### `-b, --source-branch <branch>`
 
-指定文档的分支，最终生成前往 GitHub 的链接。
+指定文档的分支，最终生成前往 GitHub 的链接，默认使用 `main`。
 
 #### `--base <dir>`
 
-指定项目的基础目录，默认会读取 `package.json` 的 `repository.directory` 字段。
-
-#### `--github <url>`
-
-指定 GitHub 地址，会渲染到导航栏中，默认会从 `package.json` 和本地 `.git` 目录中读取。
+指定项目的基础目录，默认会读取 `package.json` 的 `repository.directory` 字段，这在 monorepo 项目中很有用。
 
-#### `--footer <string>`
+#### `-d, --source-dir <dir>`
 
-使用 Markdown 自定义渲染页脚。
+指定文档目录在 GitHub 中的位置，最终生成前往 GitHub 的链接，默认使用当前命令指定目录，
+只有当命令执行位置在项目子目录时才会用到。
 
-#### `--display-rank`
+#### `--build`
 
-在 URL 中显示用于排序的值。
+输出所有前端资源。
 
 #### `--home-mode`
 
@@ -57,7 +54,9 @@ npx gem-book -h
 指定导航栏外部链接，例如：
 
 ```bash
-npx gem-book docs --nav Example,https://example.com --nav MyWebsite,https://my.website
+npx gem-book docs \
+  --nav Example,https://example.com \
+  --nav MyWebsite,https://my.website
 ```
 
 #### `--ga <id>`
@@ -78,11 +77,15 @@ npx gem-book docs --nav Example,https://example.com --nav MyWebsite,https://my.w
 
 #### `--theme <name or path>`
 
-使用内置主题或者自定义主题。
+使用内置主题或者自定义主题，支持有默认导出的模块。
 
-#### `--build`
+#### `--footer <string>`
 
-输出所有前端资源和 `<gem-book>` 渲染数据。
+使用 Markdown 自定义渲染页脚。
+
+#### `--display-rank`
+
+在 URL 中显示用于排序的值。
 
 #### `--json`
 
@@ -94,4 +97,4 @@ npx gem-book docs --nav Example,https://example.com --nav MyWebsite,https://my.w
 
 #### `--debug`
 
-输出调试信息：`gem-book.json`, `stats.json`, `source-map`。
+输出调试信息：应用的命令行选项, `stats.json`, `source-map`。

packages/gem-book/docs/zh/002-guide/004-metadata.md

@@ -7,6 +7,7 @@
 title: 侧边栏标题
 isNav: true
 navTitle: 导航栏标题
+navOrder: 2 # 导航栏位置
 sidebarIgnore: true
 ---
 
@@ -32,7 +33,7 @@ redirect: ./new.md
 > [!WARNING]
 > 不支持为文件夹指定重定向
 
-## 文件夹配置
+## 文件夹配置 {#dir}
 
 文件夹有时候也需要指定名称（例如[多语言情况下的标题](./002-i18n.md)）和在侧边栏/导航栏中的显示方式，可以在该文件夹中添加 `config.yml` 来完成，例如：
 

packages/gem-book/docs/zh/002-guide/007-extension.md

@@ -1,6 +1,6 @@
 # 扩展
 
-`<gem-book>` 渲染 Markdown，同时也扩展了 Markdown 语法。另外还提供一些方法让用户自定义 `<gem-book>`。
+GemBook 使用 [`marked`](https://github.com/markedjs/marked) 渲染 Markdown，默认支持 [CommonMark](http://spec.commonmark.org/0.30/) 和 [GitHub Flavored Markdown](https://github.github.com/gfm/)，GemBook 扩展了 Markdown 语法，另外还提供一些方法让用户自定义 GemBook。
 
 ## Markdown 增强
 
@@ -12,37 +12,18 @@
 ```
 ````
 
-下面是在 `<gbp-sandpack>` [插件](#plugins)中写代码块的例子：
+例如使用高亮：
 
-<gbp-sandpack dependencies="@mantou/gem">
+````md 1
+# 代码块信息
 
-```js index.js
-import { render } from '@mantou/gem';
+```md 1
+# 代码块信息
 
-render('这是一个 `<gbp-sandpack>` 例子', document.getElementById('root'));
-```
-
-````md README.md active 12-13
-<gbp-sandpack dependencies="@mantou/gem">
-
-```js index.js
-import { render } from '@mantou/gem';
-
-render('这是一个 `<gbp-sandpack>` 例子', document.getElementById('root'));
-```
-
-```md README.md active 3-4
-# `<gbp-sandpack>`
-
-- `<gbp-sandpack>` 中的代码块代表一个文件
-- 默认第一个文件的状态为 `active`，如果手动指定状态，必须写文件名
+...
 ```
-
-</gbp-sandpack>
 ````
 
-</gbp-sandpack>
-
 ### 固定标题锚点 Hash {#fixed-hash}
 
 默认会根据标题文本字段生成 hash，但有时你需要固定 hash，比如国际化时。
@@ -70,13 +51,13 @@ render('这是一个 `<gbp-sandpack>` 例子', document.getElementById('root'));
 <gbp-raw src="docs/template.html" range="8--4"></gbp-raw>
 
 > [!NOTE]
-> 可以使用 `--template` 指定模板文件
+> 使用 `--template` 指定模板文件才能使用插槽
 
 ## 插件 {#plugins}
 
 ### 使用插件
 
-`<gem-book>` 使用自定义元素作为插件系统，他们可以自定义渲染 Markdown 内容或者增强 `<gem-book>` 的能力。下面是内置插件 `<gbp-raw>` 的使用方式：
+GemBook 使用自定义元素作为插件系统，他们可以自定义渲染 Markdown 内容或者增强 GemBook 的能力。下面是内置插件 `<gbp-raw>` 的使用方式：
 
 <gbp-code-group>
 
@@ -99,7 +80,7 @@ gem-book docs --plugin raw
 在[这里](../003-plugins.md)查看所有内置插件。
 
 > [!TIP]
-> 在 MarkDown 中使用插件时 Attribute 不应该换行，否则会作为内联元素被 `<p>` 标签打断。
+> 在 Markdown 中使用插件时 Attribute 不应该换行，否则会作为内联元素被 `<p>` 标签打断。
 > GemBook 内置插件支持自动导入，缺点是渲染文档后才会加载，有可能页面会闪烁。
 
 ### 开发插件

packages/gem-book/docs/zh/002-guide/README.md

@@ -5,11 +5,11 @@ navTitle: 指南
 
 # 简介
 
-`gem-book` 将 [Markdown](https://zh.wikipedia.org/wiki/Markdown) 内容渲染成网站，根据目录结构生成页面。`gem-book` 是为 [Gem](https://github.com/mantou132/gem) 创建的文档生成工具，其本身也是使用 Gem 编写，和 Gem 是共生关系，它使用自定义元素 `<gem-book>` 渲染内容。
+GemBook 将 [Markdown](https://zh.wikipedia.org/wiki/Markdown) 内容渲染成网站，根据目录结构生成页面。GemBook 是为 [Gem](https://github.com/mantou132/gem) 创建的文档生成工具，其本身也是使用 Gem 编写，和 Gem 是共生关系，它使用自定义元素 `<gem-book>` 渲染内容。
 
 ## 快速开始
 
-> [!NOTE] `gem-book` 依赖 [Node.js v14+](https://nodejs.org/)，请确保 `node -v` 命令能够执行
+> [!WARNING] GemBook 依赖 [Node.js v18+](https://nodejs.org/)，请确保 `node -v` 命令能够执行
 
 ```bash
 # 创建文档
@@ -28,7 +28,7 @@ npx gem-book docs -t MyApp -i logo.png
 npx gem-book docs -t MyApp -i logo.png --home-mode
 
 # 构建前端资源
-npx gem-book docs -t MyApp -i logo.png --home-mode --build
+npx gem-book docs -t MyApp -i logo.png --home-mode --build --output dist
 
 ```
 

packages/gem-book/docs/zh/003-plugins.md

@@ -6,7 +6,7 @@ isNav: true
 
 ## `<gbp-code-group>`
 
-用于显示几段相似的代码：
+用于显示几段相似功能的代码：
 
 <gbp-code-group>
 
@@ -56,7 +56,7 @@ yarn add gem-book
 
 ## `<gbp-import>`
 
-动态导入模块，这可以用来按需加载插件，比如下面这个自定义元素是动态编译并加载的：
+动态导入模块，这可以用来按需加载插件，比如下面这个自定义元素是动态（`.ts` 文件会使用 [esm.sh](https://esm.sh/) 编译 ）加载的：
 
 <gbp-import src="docs/hello.ts"></gbp-import>
 
@@ -83,7 +83,11 @@ yarn add gem-book
 
 ```html
 <gem-book>
-  <gbp-comment slot="main-after" client-id="xxx" client-secret="xxx"></gbp-comment>
+  <gbp-comment
+    slot="main-after"
+    client-id="xxx"
+    client-secret="xxx"
+  ></gbp-comment>
 </gem-book>
 ```
 
@@ -98,7 +102,10 @@ import { render, html } from '@mantou/gem';
 
 import 'duoyun-ui/elements/button';
 
-render(html`<dy-button>Time: ${new Date().toLocaleString()}</dy-button>`, document.getElementById('root'));
+render(
+  html`<dy-button>Time: ${new Date().toLocaleString()}</dy-button>`,
+  document.getElementById('root'),
+);
 ```
 
 </gbp-sandpack>
@@ -111,7 +118,10 @@ import { render, html } from '@mantou/gem';
 
 import 'duoyun-ui/elements/button';
 
-render(html`<dy-button>Time: ${new Date().toLocaleString()}</dy-button>`, document.getElementById('root'));
+render(
+  html`<dy-button>Time: ${new Date().toLocaleString()}</dy-button>`,
+  document.getElementById('root'),
+);
 ```
 
 </gbp-sandpack>

packages/gem-book/docs/zh/README.md

@@ -1,30 +1,30 @@
 ---
 hero:
-  title: <gem-book>
+  title: GemBook
   desc: 简单、快速创建你的文档网站
   actions:
     - text: 快速开始
       link: ./002-guide/README.md
 features:
   - title: 开箱即用
-    desc: 只需运行命令行就能打包所有前端资源，让所有注意力都能放在文档编写上
+    desc: 只需运行一条命令就能构建所有前端资源，让所有注意力都能放在文档编写上。
   - title: 高性能
-    desc: 没有多余的依赖，整个应用将使用精简的代码流畅的运行
+    desc: 没有多余的依赖，整个应用将使用精简的代码流畅的运行。
   - title: 可插拔可扩展
-    desc: 能将自定义元素插入已有的网站中；使用自定义元素也能非常方便的自定义展示文档
+    desc: 能将自定义元素插入已有的网站中；使用自定义元素也能非常方便的自定义展示文档。
 ---
 
 ## 轻松上手
 
 ```bash
 # 创建文档
-mkdir docs && echo '# Hello <gem-book>!' > docs/readme.md
+mkdir docs && echo '# Hello GemBook!' > docs/readme.md
 
-# 启动本地服务打开文档站，修改文档将自动刷新
+# 启动本地服务打开文档站，修改文档将自动更新
 npx gem-book docs
 
 # 构建前端资源
-npx gem-book docs --build
+npx gem-book docs --build --output dist
 ```
 
 ## 反馈与共建