feat: add rewrite config.

jaywcjlove · Mar 28, 2024 · 9e37afe · 9e37afe
1 parent 2d4553b
commit 9e37afe
Show file tree

Hide file tree

Showing 5 changed files with 120 additions and 21 deletions.
diff --git a/.idoc/.filesStat.json b/.idoc/.filesStat.json
@@ -36,9 +36,9 @@
     "birthtime": "2022-04-10T14:24:24.106Z"
   },
   "docs/introduce/api/config.md": {
-    "atime": "2024-03-25T14:35:20.630Z",
-    "mtime": "2024-03-25T14:35:34.008Z",
-    "ctime": "2024-03-25T14:35:34.008Z",
+    "atime": "2024-03-28T07:56:39.896Z",
+    "mtime": "2024-03-28T07:56:40.026Z",
+    "ctime": "2024-03-28T07:56:40.026Z",
     "birthtime": "2024-03-25T14:35:19.401Z"
   },
   "docs/introduce/getting-started/installation.md": {

diff --git a/demo.idocrc.mjs b/demo.idocrc.mjs
@@ -0,0 +1,67 @@
+export default {
+  rewrite: (node, index, parent) => {
+    console.log(index)
+  },
+  "output": "dist",
+  "site": "iDoc {{version}}",
+  "cacheFileStat": true,
+  "homepage": "https://wangchujiang.com/idoc/",
+  "theme": "default",
+  "logo": "./logo.png",
+  "favicon": "./logo.png",
+  "keywords": "idoc,document,doc",
+  "openSource": "https://github.com/jaywcjlove/idoc",
+  "editButton": {
+    "label": "Edit this page on GitHub",
+    "url": "https://github.com/jaywcjlove/idoc/blob/master/"
+  },
+  "scope": [
+    "introduce",
+    "markdown"
+  ],
+  "data": {
+    "site_name": "idoc"
+  },
+  "meta": [
+    "<meta name=\"author\" content=\"Kenny Wong\">",
+    "<meta property=\"og:site_name\" content=\"<%= data.site_name %>\">",
+    "<meta property=\"og:url\" content=\"<%=homepage%><%=RESOLVE_PATH%>\">",
+    "<meta property=\"og:image\" content=\"<%=homepage%>logo.png\">",
+    "<meta property=\"og:type\" content=\"website\">",
+    "<meta property=\"og:title\" content=\"<%= title %> - idoc\">",
+    "<meta property=\"og:description\" content=\"<%= description%>\">",
+    "<meta property=\"twitter:image:src\" content=\"<%=homepage%>assets/banner.png\">",
+    "<meta property=\"twitter:site\" content=\"@jaywcjlove\">",
+    "<meta property=\"twitter:creator\" content=\"jaywcjlove\">",
+    "<meta property=\"twitter:card\" content=\"summary_large_image\">",
+    "<meta property=\"twitter:title\" content=\"<%= title %>\">",
+    "<meta property=\"twitter:description\" content=\"<%= description%>\">"
+  ],
+  "copyAssets": [
+    "*/assets/*.(png|jpg)"
+  ],
+  "menus": {
+    "Home": "index.html",
+    "Docs": "introduce/getting-started/installation.html",
+    "Markdown": "markdown/basic-syntax.html",
+    "About": "about.html"
+  },
+  "footer": "Released under the MIT License. Copyright © {{idocYear}} Kenny Wong<br />\nGenerated by <a href=\"https://github.com/jaywcjlove/idoc\" target=\"_blank\">idoc</a> v{{idocVersion}}\n",
+  "giscus": {
+    "src": "https://giscus.app/client.js",
+    "data-repo": "jaywcjlove/idoc",
+    "data-repo-id": "MDEwOlJlcG9zaXRvcnk0MjM4MTA2Nw==",
+    "data-category": "Q&A",
+    "data-category-id": "DIC_kwDOAoavC84CZOtP",
+    "data-mapping": "pathname",
+    "data-strict": 0,
+    "data-reactions-enabled": 1,
+    "data-emit-metadata": 0,
+    "data-input-position": "top",
+    "data-theme": "dark",
+    "data-lang": "zh-CN",
+    "data-loading": "lazy",
+    "crossorigin": "anonymous",
+    "async": true
+  }
+}
diff --git a/docs/introduce/api/config.md b/docs/introduce/api/config.md
@@ -13,7 +13,10 @@
 
 ## `idoc.yml`
 
-在你的配置最顶端添加配置 [schema](https://www.schemastore.org/)，进行数据有效性的验证，方便排出您的配置错误问题，如果你是 [Visual Studio Code](https://code.visualstudio.com/) 需要按照 [YAML](https://github.com/redhat-developer/vscode-yaml.git) 插件支持这一特性。`v1.26+` 支持添加如下更多类型的配置文件：
+在你的配置顶部添加 [schema](https://www.schemastore.org/)，进行数据有效性验证，有助于解决配置错误问题。如果你使用 [Visual Studio Code](https://code.visualstudio.com/)，需要安装 [YAML](https://github.com/redhat-developer/vscode-yaml.git) 插件来支持此功能。从 `v1.26` 版本开始，支持更多类型的配置文件：
+
+> [!NOTE/注意]
+> 由 [Auto Config Loader](https://github.com/jaywcjlove/auto-config-loader) 提供动力支持多种格式的配置。
 
 ```bash
 idoc.yml                   .idoc.yml
@@ -318,7 +321,9 @@ element:
   # 用于定义最外层宽度样式
   wrapper: style=max-width:690px;
 ```
-注意 ⚠️：目前只扩展了一个 `wrapper`
+
+> [!WARNING]
+> 目前只扩展了一个 `wrapper`
 
 ### `homepage`
 
@@ -328,7 +333,8 @@ element:
 homepage: https://jaywcjlove.github.io/idoc/
 ```
 
-注意 ⚠️：[Google 文档](https://developers.google.com/search/docs/advanced/sitemaps/build-sitemap?hl=zh-cn#text)。
+> [!TIP]
+> 提示请查看 [Google 文档](https://developers.google.com/search/docs/advanced/sitemaps/build-sitemap?hl=zh-cn#text)。
 
 ### `minify`
 
@@ -360,7 +366,8 @@ copyAssets:
   - '**/assets/*.ogm'
 ```
 
-注意 ⚠️：在 `markdown` 中引入图片等资源会自动拷贝，不需要配置 `copyAssets`。
+> [!TIP]
+> 在 `markdown` 中引入图片等资源会自动拷贝，不需要配置 `copyAssets`。
 
 ### `theme`
 
@@ -419,24 +426,25 @@ menus:
   Markdown: markdown/basic-syntax.html markdown
 ```
 
-⚠️ 注意：
-
-- 范围 `scope` 配置，在匹配到的页面，展示匹配中的章节(SiderBar)菜单。
-- 范围 `scope` 没有配置，所有页面展示章节(SiderBar)菜单。
-- 范围是匹配文件路径，配置使用 `/` idoc 工具帮助转换兼容 Windows。
-- 范围 `scope` 配置，是过滤 `idoc.chapters.yml` 中的数据。
+> [!TIP]
+> 
+> - 范围 `scope` 配置，在匹配到的页面，展示匹配中的章节(SiderBar)菜单。
+> - 范围 `scope` 没有配置，所有页面展示章节(SiderBar)菜单。
+> - 范围是匹配文件路径，配置使用 `/` idoc 工具帮助转换兼容 Windows。
+> - 范围 `scope` 配置，是过滤 `idoc.chapters.yml` 中的数据。
 
 ### `scopePrivate`
 
 某一些页面展示指定范围的的章节(SiderBar)菜单，其它页面展示剩余范围的的章节(SiderBar)菜单。
 
-> ⚠️ 注意：需要删除 ~~`scope`~~ 配置选项，上面需求才能实现。
-
 ```yml
 scopePrivate: 
   - tutorial
 ```
 
+> [!TIP]
+>  注意：需要删除 ~~`scope`~~ 配置选项，上面需求才能实现。
+
 ### `sideEffectFiles`
 
 添加副作用 `Markdown` 文件，如果你有一些文件不在指定文档目录（默认 `docs`），这些文件不会编译输出 `html`，也不会监听，通过 `sideEffectFiles` 配置，将实现在指定文档目录之外的 `Markdown` 文档也能编译。
@@ -446,7 +454,8 @@ sideEffectFiles:
   - README.zh.md
 ```
 
-⚠️ 注意：如果你在实时编译文档，修改此配置将需要重启监听服务。
+> [!TIP]
+>  注意：如果你在实时编译文档，修改此配置将需要重启监听服务。
 
 ### `menus`
 
@@ -471,7 +480,8 @@ menus:
   Docs: introduce/getting-started/installation.html introduce
 ```
 
-🚧  注意：这个 `scope` 范围，如果没有任何菜单定义 `scope` 范围，将在所有页面展示一样的 `SiderBar` 左侧边菜单栏。如果你定义了 `scope`，根据你定义的范围(`scope`) 在匹配页面路由，将在侧边栏展示不同的 `SiderBar`。`SiderBar` 需要在 `idoc.chapters.yml` 中定义，并且需要在 `idoc.yml` 中定义 `menus`。
+> [!TIP]
+>  注意：这个 `scope` 范围，如果没有任何菜单定义 `scope` 范围，将在所有页面展示一样的 `SiderBar` 左侧边菜单栏。如果你定义了 `scope`，根据你定义的范围(`scope`) 在匹配页面路由，将在侧边栏展示不同的 `SiderBar`。`SiderBar` 需要在 `idoc.chapters.yml` 中定义，并且需要在 `idoc.yml` 中定义 `menus`。
 
 ### `footer`
 
@@ -540,11 +550,27 @@ giscus:
   async: true
 ```
 
-🚧 请注意，必须满足下面 3 点配置才能起作用：
+> [!TIP]
+>  请注意，必须满足下面 3 点配置才能起作用：
+>
+> 1. 该仓库是[公开的](https://docs.github.com/en/github/administering-a-repository/managing-repository-settings/setting-repository-visibility#making-a-repository-public)，否则访客将无法查看 discussion。
+> 2. [giscus app](https://github.com/apps/giscus) 已安装，否则访客将无法评论和回应。
+> 3. Discussions 功能已[在你的仓库中启用](https://docs.github.com/en/github/administering-a-repository/managing-repository-settings/enabling-or-disabling-github-discussions-for-a-repository)。
+
+### `rewrite`
+
+这是利用 rehype 插件 [rehype-rewrite](https://github.com/jaywcjlove/rehype-rewrite) 对 HTML 元素进行重写，可帮助您修改页面上的任何 HTML 元素和文档内容。以下配置仅在 JS 配置中生效：
+
+```js
+// .idocrc.mjs
+export default {
+  rewrite: (node, index, parent) => {
+    console.log(index)
+  },
+}
+```
 
-1. 该仓库是[公开的](https://docs.github.com/en/github/administering-a-repository/managing-repository-settings/setting-repository-visibility#making-a-repository-public)，否则访客将无法查看 discussion。
-2. [giscus app](https://github.com/apps/giscus) 已安装，否则访客将无法评论和回应。
-3. Discussions 功能已[在你的仓库中启用](https://docs.github.com/en/github/administering-a-repository/managing-repository-settings/enabling-or-disabling-github-discussions-for-a-repository)。
+应用示例 [RegExp Example](https://github.com/jaywcjlove/regexp-example)，这个示例是一个正则表达式搜集备忘清单，我们将在这个示例生成 HTML 的同时，给示例添加验证功能等自定义特性。
 
 ## `idoc.chapters.yml`
 

diff --git a/src/markdown/markdown.ts b/src/markdown/markdown.ts
@@ -148,6 +148,9 @@ export async function createHTML(mdStr: string = '', fromPath: string, toPath: s
     if (node.type === 'comment' && /^idoc:config:/i.test(node.value.trimStart())) {
       configMarkdownStr = node.value.replace(/^idoc:config:/i, '');
     }
+    if (config.data.rewrite && typeof config.data.rewrite === 'function') {
+      config.data.rewrite(node, index, parent);
+    }
   };
   const mdHtml = (await markdownToHTML(mdStr, mdOptions)) as string;
   const tocsArr = tocs.map((item) => ({

diff --git a/src/utils/conf.ts b/src/utils/conf.ts
@@ -6,6 +6,7 @@ import image2uri from 'image2uri';
 import readdirFiles, { IFileDirStat, getStat } from 'recursive-readdir-files';
 import { autoConf, merge, getConfigPath } from 'auto-config-loader';
 import { createRequire } from 'node:module';
+import { Options } from '@wcj/markdown-to-html';
 import { logo } from './logo.js';
 import { PageConfig, Toc } from '../markdown/markdown.js';
 import { isAbsoluteURL, isOutReadme } from '../markdown/utils.js';
@@ -79,6 +80,8 @@ export interface SiteGlobalConfig {
   data?: Record<string, any>;
   theme?: string;
   sideEffectFiles?: Array<string>;
+  /** Rewrite Element. [rehype-rewrite](https://github.com/jaywcjlove/rehype-rewrite#rewritenode-index-parent-void) */
+  rewrite?: Options['rewrite'];
 }
 
 export interface Config extends SiteGlobalConfig {