[gem-book] Add <gbp-include> <gbp-var>

Closed #111, #112
mantou132 · Jan 8, 2024 · 8337376 · 8337376
1 parent bd4c920
commit 8337376
Show file tree

Hide file tree

Showing 30 changed files with 330 additions and 158 deletions.
diff --git a/packages/gem-book/docs/en/002-guide/005-theme.md b/packages/gem-book/docs/en/002-guide/005-theme.md
@@ -19,11 +19,11 @@ Of course, you can also set the theme directly using the DOM API of `<gem-book>`
 
 <gbp-code-group>
 
-```js DOM
+```js vanilla.js
 new GemBookElement(config, theme);
 ```
 
-```js Lit
+```js lit
 html`<gem-book .config=${config} .theme=${theme}></gem-book>`;
 ```
 

diff --git a/packages/gem-book/docs/en/002-guide/007-extension.md b/packages/gem-book/docs/en/002-guide/007-extension.md
@@ -95,11 +95,11 @@ import plugin:
 
 <gbp-code-group>
 
-```bash CLI
+```bash cli
 gem-book docs --plugin raw
 ```
 
-```html HTML
+```html html
 <script type="module" src="https://unpkg.com/gem-book/plugins/raw.js"></script>
 ```
 

diff --git a/packages/gem-book/docs/zh/002-guide/003-cli.md b/packages/gem-book/docs/zh/002-guide/003-cli.md
@@ -75,6 +75,10 @@ npx gem-book docs \
 
 指定文档目录是否支持[国际化](./002-i18n.md)。
 
+#### `--ignored <string>`
+
+忽略的文件，使用 [`anymatch`](https://github.com/micromatch/anymatch) 格式，默认 `**/node_modules/**`
+
 #### `--plugin <name or path>`
 
 加载插件，可添加多个。也可以使用 URL 或者相对路径提供自定义插件，支持 TypeScript 模块。

diff --git a/packages/gem-book/docs/zh/002-guide/005-theme.md b/packages/gem-book/docs/zh/002-guide/005-theme.md
@@ -19,11 +19,11 @@ gem-book docs --theme dark
 
 <gbp-code-group>
 
-```js DOM
+```js vanilla.js
 new GemBookElement(config, theme);
 ```
 
-```js Lit
+```js lit
 html`<gem-book .config=${config} .theme=${theme}></gem-book>`;
 ```
 

diff --git a/packages/gem-book/docs/zh/002-guide/007-extension.md b/packages/gem-book/docs/zh/002-guide/007-extension.md
@@ -71,11 +71,11 @@ GemBook 使用自定义元素作为插件系统，他们可以自定义渲染 Ma
 
 <gbp-code-group>
 
-```bash CLI
+```bash cli
 gem-book docs --plugin raw
 ```
 
-```html HTML
+```html html
 <script type="module" src="https://unpkg.com/gem-book/plugins/raw.js"></script>
 ```
 
@@ -90,8 +90,15 @@ gem-book docs --plugin raw
 在[这里](../003-plugins.md)查看所有内置插件。
 
 > [!TIP]
-> 在 Markdown 中使用插件时 Attribute 不应该换行，否则会作为内联元素被 `<p>` 标签打断。
-> GemBook 内置插件支持自动导入，缺点是渲染文档后才会加载，有可能页面会闪烁。
+>
+> 1. 在 Markdown 中使用插件时 Attribute 不应该换行，否则会作为内联元素被 `<p>` 标签打断。
+> 2. GemBook 内置插件支持自动导入，缺点是渲染文档后才会加载，有可能页面会闪烁。
+> 3. VSCode 默认不能在 MarkDown 文件中使用 [Emmet](https://code.visualstudio.com/docs/editor/emmet)，你可以通过设置启用：
+>
+>    ```json
+>    "emmet.excludeLanguages": [],
+>    "emmet.includeLanguages": {"markdown": "html"},
+>    ```
 
 ### 开发插件
 

diff --git a/packages/gem-book/docs/zh/003-plugins.md b/packages/gem-book/docs/zh/003-plugins.md
@@ -10,11 +10,11 @@ isNav: true
 
 <gbp-code-group>
 
-```bash NPM
+```bash npm
 npm i gem-book
 ```
 
-```bash YARN
+```bash yarn
 yarn add gem-book
 ```
 
@@ -23,11 +23,11 @@ yarn add gem-book
 ````md
 <gbp-code-group>
 
-```bash NPM
+```bash npm
 npm i gem-book
 ```
 
-```bash YARN
+```bash yarn
 yarn add gem-book
 ```
 
@@ -36,16 +36,26 @@ yarn add gem-book
 
 ## `<gbp-raw>`
 
-用于显示远端代码，如果提供的 `src` 只包含路径，则会从当前项目的 GitHub 上读取内容（受 [`sourceDir`](./002-guide/003-cli.md#--source-dir)，[`sourceBranch`](./002-guide/003-cli.md#--source-branch) 影响），比如：
+用于显示远端代码，如果提供的 `src` 只包含路径，则会从当前项目的 GitHub 上读取内容（受 [`sourceDir`](./002-guide/003-cli.md#--source-dir)，[`sourceBranch`](./002-guide/003-cli.md#--source-branch) 影响），例如：
 
-<gbp-raw src="package.json" range="2-3,-4--6" highlight="-5"></gbp-raw>
+<gbp-raw src="package.json" range="2-3,-4--6,author-license" highlight="-5,author"></gbp-raw>
 
 ```md
-<!-- `range` 指定显示的范围，支持使用负数 -->
+<!-- `range` 指定显示的范围，支持使用负数、字符串匹配，`highlight` 格式一样 -->
 
-<gbp-raw src="package.json" range="2-3,-4--6" highlight="-5"></gbp-raw>
+<gbp-raw src="package.json" range="2-3,-4--6,author-license" highlight="-5,author"></gbp-raw>
 ```
 
+## `<gbp-var>`
+
+引用全局变量：<gbp-var>hello</gbp-var>
+
+```md
+<gbp-var>hello</gbp-var>
+```
+
+变量需要在[配置文件](./002-guide/003-cli.md)中定义。
+
 ## `<gbp-media>`
 
 显示远端多媒体内容，比如图片，视频，获取资源方式和 `<gbp-raw>` 一样：
@@ -54,6 +64,18 @@ yarn add gem-book
 <gbp-media src="preview.png"></gbp-media>
 ```
 
+## `<gbp-include>`
+
+动态加载显示 MarkDown 片段：
+
+<gbp-include src="./002-guide/007-extension.md" range="[!NOTE]->"></gbp-include>
+
+```md
+<!-- `range` 语法和 `<gbp-raw>` 一样，这里的 `range` 使用字符串匹配 -->
+
+<gbp-include src="./002-guide/007-extension.md" range="[!NOTE]->"></gbp-include>
+```
+
 ## `<gbp-import>`
 
 动态导入模块，这可以用来按需加载插件，比如下面这个自定义元素是动态（`.ts` 文件会使用 [esm.sh](https://esm.sh/) 编译 ）加载的：

diff --git a/packages/gem-book/gem-book.cli.json b/packages/gem-book/gem-book.cli.json
@@ -8,5 +8,8 @@
   "plugin": ["raw", "docsearch", "api", "sandpack", "code-group", "import"],
   "template": "docs/template.html",
   "ga": "G-PZYZ441YD3",
-  "debug": true
+  "debug": true,
+  "global": {
+    "hello": "Hello World!"
+  }
 }
diff --git a/packages/gem-book/package.json b/packages/gem-book/package.json
@@ -1,6 +1,6 @@
 {
   "name": "gem-book",
-  "version": "1.5.31",
+  "version": "1.5.32",
   "description": "Create your document website easily and quickly",
   "keywords": [
     "doc",

diff --git a/packages/gem-book/schema.json b/packages/gem-book/schema.json
@@ -29,6 +29,7 @@
         "github": {
           "type": "string"
         },
+        "global": {},
         "homeMode": {
           "type": "boolean"
         },
@@ -38,6 +39,12 @@
         "icon": {
           "type": "string"
         },
+        "ignored": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
         "json": {
           "type": "boolean"
         },

diff --git a/packages/gem-book/src/common/config.ts b/packages/gem-book/src/common/config.ts
@@ -24,6 +24,7 @@ interface CommonConfig {
   displayRank?: boolean;
   homeMode?: boolean;
   footer?: string;
+  global?: any;
 }
 
 export type BookConfig = {

diff --git a/packages/gem-book/src/element/elements/homepage.ts b/packages/gem-book/src/element/elements/homepage.ts
@@ -2,7 +2,7 @@ import { html, GemElement, customElement, part, connectStore, css } from '@manto
 import { mediaQuery } from '@mantou/gem/helper/mediaquery';
 
 import { theme } from '../helper/theme';
-import { getRemotePath, getUserLink, NavItemWithLink } from '../lib/utils';
+import { getUserLink, joinPath, NavItemWithLink } from '../lib/utils';
 import { bookStore } from '../store';
 
 import { icons } from './icons';
@@ -167,8 +167,7 @@ export class Homepage extends GemElement {
                 ${feature.icon
                   ? html`<img
                       class="icon"
-                      src=${new URL(feature.icon, `${location.origin}${getRemotePath(originLink, bookStore.lang)}`)
-                        .href}
+                      src=${new URL(feature.icon, `${location.origin}${joinPath(bookStore.lang, originLink)}`).href}
                     />`
                   : ''}
                 <dt class="feat-title">${feature.title}</dt>

diff --git a/packages/gem-book/src/element/elements/main.ts b/packages/gem-book/src/element/elements/main.ts
@@ -26,19 +26,23 @@ const parser = new DOMParser();
 
 // https://github.com/w3c/csswg-drafts/issues/9712
 const style = createCSSSheet(css`
-  :not(:defined) {
-    display: block;
+  :not(gbp-var):not(:defined) {
+    display: contents;
+    color: transparent;
+    /* maybe browser limit */
     font-size: 0;
   }
-  :not(:defined) * {
+  :not(gbp-var):not(:defined) * {
     display: none;
   }
-  :not(:defined)::before {
+  :not(gbp-var):not(:defined)::before {
     font-size: 1rem;
     display: block;
     content: 'The element is not defined';
-    padding: 1em;
+    padding: 2rem;
+    margin-block: 2rem;
     text-align: center;
+    color: ${theme.textColor};
     background: ${theme.borderColor};
     border-radius: ${theme.normalRound};
   }
@@ -350,7 +354,10 @@ export class Main extends GemElement {
 
         this.#updateToc();
 
-        const mo = new MutationObserver(this.#updateToc);
+        const mo = new MutationObserver(() => {
+          checkBuiltInPlugin(this.shadowRoot!);
+          this.#updateToc();
+        });
         mo.observe(this.shadowRoot!, {
           childList: true,
           subtree: true,

diff --git a/packages/gem-book/src/element/elements/meta.ts b/packages/gem-book/src/element/elements/meta.ts
@@ -1,7 +1,7 @@
 import { connectStore, customElement, GemElement, html } from '@mantou/gem';
 import { mediaQuery } from '@mantou/gem/helper/mediaquery';
 
-import { getRemotePath, getURL } from '../lib/utils';
+import { getURL, joinPath } from '../lib/utils';
 import { themeStore } from '../helper/theme';
 import { bookStore, locationStore } from '../store';
 
@@ -10,7 +10,7 @@ import '@mantou/gem/elements/reflect';
 function getAlternateUrl(lang: string, pathname?: string) {
   const { origin } = location;
   const { path, query, hash } = locationStore;
-  const fullPath = getRemotePath(pathname || path, lang);
+  const fullPath = joinPath(lang, pathname || path);
   if (pathname) return `${origin}${fullPath}`;
   return `${origin}${fullPath}${query}${hash}`;
 }
@@ -36,7 +36,10 @@ export class Meta extends GemElement {
           ? null
           : currentLinks
               ?.filter((e) => e.type === 'file')
-              .map(({ originLink, hash }) => html`<link rel="prefetch" href=${getURL(originLink, lang, hash)}></link>`)}
+              .map(
+                ({ originLink, hash }) =>
+                  html`<link rel="prefetch" href=${getURL(joinPath(lang, originLink), hash)}></link>`,
+              )}
 
         <!-- search engine -->
         <link rel="canonical" href=${canonicalLink} />