[gem-book] Improve compatible

mantou132 · Jan 6, 2024 · 4dfdacf · 4dfdacf
1 parent 7621db1
commit 4dfdacf
Show file tree

Hide file tree

Showing 20 changed files with 167 additions and 137 deletions.
diff --git a/packages/duoyun-ui/docs/.gitignore b/packages/duoyun-ui/docs/.gitignore
diff --git a/packages/gem-book/docs/zh/002-guide/002-i18n.md b/packages/gem-book/docs/zh/002-guide/002-i18n.md
@@ -1,21 +1,27 @@
 # 国际化
 
-只需要将文档移动到以语言代码命名的文件夹中即可，例如：
-
-```
-docs/
-├── en
-│   ├── 002-guide
-│   │   ├── README.md
-│   │   └── installation.md
-│   ├── 003-about.md
-│   └── README.md
-└── zh
-    ├── 002-guide
-    │   ├── README.md
-    │   └── installation.md
-    └── README.md
-```
+GemBook 很容易让文档站支持多语言，语言代码显示在 URL 路径中：`/{lang}/path`。
+访问网站时如果路径中包含语言代码，则会显示该语言版本，如果没有则根据浏览器设置选择最合适的语言并进行重定向。
+
+## 启用国际化
+
+1. 使用 [`--i18n`](./003-cli.md#--i18n) 启用国际化，这让 GemBook 自动重定向
+2. 将文档移动到以语言代码命名的文件夹中，例如：
+
+   ```
+   docs/
+   ├── en
+   │   ├── 002-guide
+   │   │   ├── README.md
+   │   │   └── installation.md
+   │   ├── 003-about.md
+   │   └── README.md
+   └── zh
+       ├── 002-guide
+       │   ├── README.md
+       │   └── installation.md
+       └── README.md
+   ```
 
 语言代码的支持请查看[这里](https://github.com/mantou132/gem/tree/master/packages/gem-book/src/bin/lang.json)。
 

diff --git a/packages/gem-book/docs/zh/002-guide/003-cli.md b/packages/gem-book/docs/zh/002-guide/003-cli.md
@@ -12,7 +12,7 @@ npx gem-book -h
 
 > [!TIP]
 > 如果用 `json` 格式，可以添加 `"$schema": "https://unpkg.com/gem-book/schema.json"` 以获取类型提示，
-> 如果使用 `js` 格式，可以导入类型 `import('gem-book/common/config').CliConfig`。
+> 如果使用 `js` 格式，可以使用 [jsdoc](https://jsdoc.app/tags-type) 导入类型 `import('gem-book/common/config').CliConfig`。
 
 ## 命令行选项
 
@@ -26,7 +26,7 @@ npx gem-book -h
 
 #### `-o, --output <path>`
 
-指定输出文件目录，默认为指定的文档目录；如果是 `json` 文件路径则只输出 [`json`](#--json) 文件。
+指定输出文件目录，默认是 `dist`；如果是 `json` 文件路径则只输出 [`json`](#--json) 文件。
 
 #### `--github <url>`
 
@@ -38,7 +38,7 @@ npx gem-book -h
 
 #### `--base <dir>`
 
-指定项目的基础目录，默认会读取 `package.json` 的 `repository.directory` 字段，这在 monorepo 项目中很有用。
+指定项目的基础目录，默认会读取 `package.json` 的 `repository.directory` 字段，这在 Monorepo 项目中很有用。
 
 #### `-d, --source-dir <dir>`
 
@@ -47,7 +47,7 @@ npx gem-book -h
 
 #### `--build`
 
-输出所有前端资源。
+构建文档站。
 
 #### `--home-mode`
 
@@ -69,23 +69,23 @@ npx gem-book docs \
 
 #### `--template <path>`
 
-指定 HTML 模版路径，可以在模版中执行额外的 `Javascript` 或者其他 `meta` 元素。
+指定 HTML 模版路径，可以在模版中执行额外的 JavaScript 或者插入一些元素。
 
 #### `--i18n`
 
 指定文档目录是否支持[国际化](./002-i18n.md)。
 
 #### `--plugin <name or path>`
 
-加载插件，可添加多个。也可以使用 URL 或者相对路径提供自定义插件。
+加载插件，可添加多个。也可以使用 URL 或者相对路径提供自定义插件，支持 TypeScript 模块。
 
 #### `--theme <name or path>`
 
 使用内置主题或者自定义主题，支持有默认导出的模块。
 
 #### `--footer <string>`
 
-使用 Markdown 自定义渲染页脚。
+自定义页脚，支持 Markdown 格式。
 
 #### `--display-rank`
 

diff --git a/packages/gem-book/docs/zh/002-guide/005-theme.md b/packages/gem-book/docs/zh/002-guide/005-theme.md
@@ -8,7 +8,7 @@
 
 ## 自定义主题
 
-可以直接使用命令行参数提供 `json`/`CommonJs/ESM` 格式的主题文件路径或者[内置主题](https://github.com/mantou132/gem/tree/master/packages/gem-book/themes)名称：
+可以直接使用命令行参数提供 `JSON`/`CommonJS`/`ESM` 格式的主题文件路径或者[内置主题](https://github.com/mantou132/gem/tree/master/packages/gem-book/themes)名称：
 
 ```bash
 gem-book docs --theme path/my-theme.mjs

diff --git a/packages/gem-book/docs/zh/002-guide/006-deploy.md b/packages/gem-book/docs/zh/002-guide/006-deploy.md
@@ -1,13 +1,13 @@
 # 部署
 
-只需要使用 `--build` 构建前端资源（`index.html`，`*.js`...），然后为输出目录提供静态服务即可。
+只需要使用 `--build` 构建前端资源（`index.html`，`*.js`...），然后为输出目录（默认为 `dist`）提供静态服务即可。
 
 > [!WARNING]
 > 由于 `<gem-book>` 使用了 [History API](https://developer.mozilla.org/en-US/docs/Web/API/History)，所以默认不支持 Github Pages
 
 ## Netlify
 
-Netlify 中配置构建脚本（`gem-book docs --build`）和发布目录（`docs`），然后在项目中 `netlify.toml` 配置重定向规则：
+Netlify 中配置构建脚本（`gem-book docs --build`）和输出目录，然后在项目中 `netlify.toml` 配置重定向规则：
 
 ```toml
 [[redirects]]
@@ -18,7 +18,7 @@ Netlify 中配置构建脚本（`gem-book docs --build`）和发布目录（`doc
 
 ## Vercel
 
-Vercel 中配置构建脚本（`gem-book docs --build`）和发布目录（`docs`），然后在项目中 `vercel.json` 配置重定向规则：
+Vercel 中配置构建脚本（`gem-book docs --build`）和输出目录，然后在项目中 `vercel.json` 配置重定向规则：
 
 ```json
 {

diff --git a/packages/gem-book/docs/zh/002-guide/007-extension.md b/packages/gem-book/docs/zh/002-guide/007-extension.md
@@ -1,9 +1,9 @@
 # 扩展
 
-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 增强
 
+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 语法。
+
 ### 代码块信息
 
 ````md
@@ -35,14 +35,24 @@ GemBook 使用 [`marked`](https://github.com/markedjs/marked) 渲染 Markdown，
 ### 高亮引用块
 
 ```md
-> [!TIP]
-> 这是[高亮引用块](https://github.com/orgs/community/discussions/16925)
+> [!NOTE]
+> 这是 [高亮引用块](https://github.com/orgs/community/discussions/16925)
 ```
 
+> [!NOTE]
+> 这是 `[!NOTE]`
+
 > [!TIP]
-> 这是[高亮引用块](https://github.com/orgs/community/discussions/16925)
+> 这是 `[!TIP]`
+
+> [!IMPORTANT]
+> 这是 `[!IMPORTANT]`
+
+> [!WARNING]
+> 这是 `[!WARNING]`
 
-支持 `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]` 和 `[!CAUTION]`。
+> [!CAUTION]
+> 这是 `[!CAUTION]`
 
 ## 插槽
 
@@ -51,7 +61,7 @@ GemBook 使用 [`marked`](https://github.com/markedjs/marked) 渲染 Markdown，
 <gbp-raw src="docs/template.html" range="8--4"></gbp-raw>
 
 > [!NOTE]
-> 使用 `--template` 指定模板文件才能使用插槽
+> 使用 [`--template`](./003-cli.md#--template-path) 指定模板文件才能使用插槽
 
 ## 插件 {#plugins}
 

diff --git a/packages/gem-book/docs/zh/002-guide/README.md b/packages/gem-book/docs/zh/002-guide/README.md
@@ -9,6 +9,8 @@ GemBook 将 [Markdown](https://zh.wikipedia.org/wiki/Markdown) 内容渲染成
 
 ## 快速开始
 
+可以直接在 [StackBlitz](https://stackblitz.com/edit/node-c7iw5d?file=README.md) 上进行在线尝试。
+
 > [!WARNING] GemBook 依赖 [Node.js v18+](https://nodejs.org/)，请确保 `node -v` 命令能够执行
 
 ```bash
@@ -44,19 +46,17 @@ npx gem-book docs -t MyApp -i logo.png --home-mode --build --output dist
 上面的命令使用 `webpack` 打包完整的前端项目，但你也可以直接在 HTML 中使用 `<gem-book>` 元素。
 
 ```bash
-# 仅生成 <gem-book> 需要的 json 文件
-npx gem-book docs -t MyApp -i logo.png --home-mode --build --json
-
 # 安装成依赖
 npm install gem-book
+
+# 仅生成 <gem-book> 需要的 json 文件
+npx gem-book docs -t MyApp -i logo.png --home-mode --build --json
 ```
 
 然后在你的项目中使用 `<gem-book>`：
 
 ```js
 import { html, render } from '@mantou/gem';
-
-// 导入 <gem-book>
 import 'gem-book';
 
 import config from './gem-book.json';

diff --git a/packages/gem-book/package.json b/packages/gem-book/package.json
@@ -1,6 +1,6 @@
 {
   "name": "gem-book",
-  "version": "1.5.28",
+  "version": "1.5.30",
   "description": "Create your document website easily and quickly",
   "keywords": [
     "doc",
@@ -28,7 +28,7 @@
   ],
   "scripts": {
     "schema": "npx ts-json-schema-generator -p src/common/config.ts -t CliConfig -o schema.json",
-    "build:cli": "esbuild ./src/bin/index.ts --outdir=./bin --platform=node --sourcemap --bundle --external:jsdom --external:lodash --external:yaml --external:front-matter --external:commander --external:webpack --external:ts-loader --external:typescript --external:webpack-dev-server --external:html-webpack-plugin --external:copy-webpack-plugin --external:workbox-webpack-plugin",
+    "build:cli": "esbuild ./src/bin/index.ts --outdir=./bin --platform=node --sourcemap --bundle --external:jsdom --external:anymatch --external:chokidar --external:jimp --external:marked --external:yaml --external:front-matter --external:commander --external:webpack --external:ts-loader --external:typescript --external:webpack-dev-server --external:html-webpack-plugin --external:copy-webpack-plugin --external:workbox-webpack-plugin",
     "start:cli": "yarn build:cli --watch",
     "docs": "node ./bin docs",
     "start:docs": "cross-env PORT=8090 GEM_BOOK_DEV=true nodemon --watch bin --exec \"yarn docs\"",
@@ -40,6 +40,8 @@
   },
   "dependencies": {
     "@mantou/gem": "^1.7.8",
+    "anymatch": "^3.1.3",
+    "chokidar": "^3.5.3",
     "commander": "^7.2.0",
     "copy-webpack-plugin": "^11.0.0",
     "front-matter": "^4.0.2",
@@ -48,7 +50,6 @@
     "html-webpack-plugin": "^5.5.3",
     "jimp": "^0.16.1",
     "jsdom": "^16.5.3",
-    "lodash": "^4.17.21",
     "marked": "^10.0.0",
     "chalk": "^2.4.2",
     "mkdirp": "^1.0.4",
@@ -66,7 +67,6 @@
     "@gemjs/config": "^1.6.11",
     "@open-wc/testing": "^2.5.33",
     "@types/jsdom": "^16.2.10",
-    "@types/lodash": "^4.14.169",
     "@types/marked": "^2.0.2",
     "@types/mkdirp": "^1.0.1",
     "@types/parse-github-url": "^1.0.0",

diff --git a/packages/gem-book/src/bin/builder.ts b/packages/gem-book/src/bin/builder.ts
@@ -7,7 +7,6 @@ import WebpackDevServer from 'webpack-dev-server';
 import HtmlWebpackPlugin from 'html-webpack-plugin';
 import CopyWebpackPlugin from 'copy-webpack-plugin';
 import { GenerateSW } from 'workbox-webpack-plugin';
-import chalk from 'chalk';
 
 import { BookConfig, CliUniqueConfig } from '../common/config';
 import { STATS_FILE } from '../common/constant';
@@ -38,7 +37,8 @@ export async function startBuilder(dir: string, options: Required<CliUniqueConfi
 
   const isRemoteIcon = isURL(icon);
   const docsDir = path.resolve(dir);
-  const outputDir = output ? path.resolve(output) : docsDir;
+  // 开发模式时使用 docsDir 避免不必要的复制
+  const outputDir = build && output ? path.resolve(output) : docsDir;
   const themePath = resolveTheme(theme);
 
   const compiler = webpack({