大家好，我是老纪。之前写了两篇关于静态站点的文章（《[静态站点全文搜索实现原理之dumi篇](https://juejin.cn/post/7355692365329301544)》和《[静态站点全文搜索实现原理之Rspress篇](https://juejin.cn/post/7356133709089308687)》），花了不少力气写的，在各个平台上都没什么水花，可能关注这块的同学比较少。比如在掘金上阅读量是这样的： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/c963b8e3bb6a42519d2ac37d8fd22244~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1456\&h=382\&s=163346\&e=png\&b=ffffff) 而 [pnpm的介绍](https://juejin.cn/post/7357554457913557027)显然更受欢迎些： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/f3169b9423554f57915f0ab8b332db5e~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1864\&h=658\&s=203608\&e=png\&b=ffffff) 这篇[修改第三方npm包的文章](https://juejin.cn/post/7356534347509497919)居然是爆款（对我而言），每天都有人点赞收藏，以至于我不得不把掘金APP的点赞收藏提示关了： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/6eb108e86c9b43eea5da3e9e25c4ef23~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1866\&h=768\&s=214446\&e=png\&b=fefefe) 在知乎上这篇《[错位之谜：网站简体中文何以变繁？](https://zhuanlan.zhihu.com/p/681624689)》的热度更高些： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/d82fb3868adc4702b24510caf551685e~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1268\&h=542\&s=170945\&e=png\&b=ffffff) 闲言少叙，言归正传。本文简单记录下某文档网站使用`dumi`后，呈现3D示例的一个骚操作。三言两语难以说尽，各位看官且听我慢慢道来。 ## 技术选型前后早在两年前，曾经有个团队问过我关于ES（Elastic Search）搜索的事情；又过了一段时间，又有同事让我调研`Galacean`（蚂蚁的一个团队）怎么实现的代码与效果展示，我研究后发现是用Markdown实现的，于是写了一篇《[Markdown自定义标签](https://juejin.cn/post/7254901061176803388)》，可能标题不够水，所以一点水花都没有。去年年底，在我的团队已经被裁的剩下大猫小猫三两只时，接到一个任务，优化某文档网站的搜索功能。我这时才意识到上面两件事其实是同一件。当前的文档网站，内容以`Markdown`为主，不存在动态的内容，只是API和示例部分都是用`iframe`嵌套。需要我们优化的搜索功能，主要是想将API、示例代码都可以搜索并定位跳转。 ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/2d23efa1191e40ec9a2bedb0517d0494~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=3022\&h=1150\&s=441988\&e=png\&b=ffffff) 于是有了三种方案： 1. 现有的功能+`ES`优化 2. 现有的功能+`algolia`等第三方搜索服务 3. `dumi`纯前端方案正常来说，我们应该选择第一种，只需要考虑将API、示例的文本存储到ES数据库，但涉及到定位跳转的话，还得考虑存储的粒度、是否需要行数、段数等元数据。而第二种方案，则是花钱买服务，`algolia`等第三方搜索服务比较成熟了，只需要通过简单的配置，搜索服务会定时扫描整个网站，前端调用相关的API就可以了。第三种方案，是我在网上看到`dumi2`的发布信息后心动了。一直以为全文搜索是后端的活儿，当数据到了某个体量后，前端不得卡死？为了能够搜索全文，前端必然需要拿到所有文本，在网络请求里会不会太大？但自己尝试后，发现对于我们的文档级别，还是可以接受的。`dumi2`使用了Web Worker来优化搜索，避免卡顿；文本虽然大，但开启`br`压缩后，4M可以压缩到600K，这点儿流量在今天看来，真是毛毛雨了。 ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/17d823842c9e40ada3cb692c2f8f05a5~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=2828\&h=954\&s=463607\&e=png\&b=f3f7f9) 再复习下`dumi`的宣传优势，吸引我的主要是这几点： 1. 全文搜索。省掉一个后端服务 2. UI比我们的要好看些，自带响应式布局、暗黑模式、多语言等 3. 可以自定义组件来扩展Markdown 看了下现有网站的功能，替换成本不高，大部分`Markdown`文件移植过来就行了。需要处理的细节集中在以下几点： 1. 首页需要定制，写个React组件`.dumi/pages/index.tsx`轻松搞定。 2. API部分，原先是使用`jsdoc`导出的HTML，将之修改为`Markdown`，再写个脚本替换下链接。 3. 示例部分，是3D与代码的结合。正常来说也是一个React组件就很容易搞定，但并没有那么简单。这也正是撰写本文的由来。 ## 示例部分的坑如果不要求全文搜索搜索到示例中的代码块，那么，写个React组件，左侧是个`iframe`，右侧是个代码块，是再简单不过了。但是，如果考虑代码块的全文搜索，就有些令人头疼了。因为，`dumi`中的搜索，只包含了静态的Markdown部分，而React组件是动态的，这点儿是做不到的。 > 这也是使用框架的弊端，必须戴着脚链跳舞。关于`dumi`的搜索原理，简单来说，是将与路由相关的文档内容作为资源加入到`Webpack`的工作流中，为此，`dumi`提供了专门的`Markdown loader`来解析处理定制的复杂规则。在项目启动后，内存中已经有了完整的文档元数据对象，使用`JavaScript`进行搜索就顺理成章了。但这个搜索过程可能会很消耗CPU，造成页面卡顿，所以`dumi`又使用了`Web Worker`，将这一环节异步处理，保障了主线程的流畅运行。详见拙作《[静态站点全文搜索实现原理之dumi篇](https://juejin.cn/post/7355692365329301544)》。应该怎么办呢？有两种思路： 1. 魔改`dumi`源码的Hook [useSiteSearch](https://d.umijs.org/theme/api#usesitesearch)，暴露一个可以注入搜索源的函数，在入口文件里找个时机调用。缺点是需要深入研究`dumi`的搜索机制，怎么将示例的代码块分段、分行、分词，都是麻烦。 2. 写一个`JavaScript`脚本，将示例的代码块批量生成多个`Markdown`文件，上面部分是`React`组件，用来呈现`3D`效果，下面部分是`JavaScript`源码。从实现成本上讲，我更倾向于第二种。但第二种，又有个缺点，它只能是上下布局，大致是这样的： ````markdown ## Thingjs Example ```jsx /** * inline: true */ import { ThingjsExample } from 'thingjs-docs'; export default () => ( ); ``` ```ts const app = new THING.App(); app.camera.position = [7, 7, 7]; ``` ```` 呈现出来的效果是这样的： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/0d7b0df0d8874b53b46fba82a5c56611~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=2496\&h=1060\&s=283096\&e=png\&b=7f7f7f) 在某些场景中，上下布局是合理的，但作为示例，显然是左右更佳些。 ### 方案一：吸星大法当我以为走进了死胡同时，突发奇想，是不是可以将示例组件回归到最初的设想，包含左右两部分布局，左侧是3D，右侧是代码块，但下方用来辅助搜索的源码代码块，可以考虑添加一个元属性，将之隐藏掉。比如`dumi`的文档里关于`Markdown`的增强有一个高亮的示例，就扩展了代码块的能力： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/74ddc141c98d465697b2b451a423176a~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1560\&h=1118\&s=129931\&e=png\&b=f9fafc) 我可以添加一个规则，比如： ````markdown ```ts | hide xxx ``` ```` 在渲染时，将相关DOM元素隐藏掉。 ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/5e4bcada0ffc4a56bc6f724104c1f0e6~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=640\&h=495\&s=410336\&e=png\&b=826744) 这思路是不是很可行？只有两点需要处理： 1. 找到`dumi`源码（搜索关键字`pure`），看能不能抄作业（其实是`SourceCode`组件） 2. 右侧的代码块，也最好复用`dumi`现成的组件 ### 方案二：乾坤大挪移当我磨刀霍霍，准备开干时，另一个更骚操作的方案涌现在我脑海里：何不来一招乾坤大挪移？ ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/53116c6cadcd432ea5ec49be6148c189~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=640\&h=360\&s=406877\&e=png\&b=637d7f) 简言之： 1. 示例组件仍是左右布局，左侧3D不变，但右侧是空的 2. 在组件渲染时，将下方的代码块移动到右侧的`div`里感觉这个思路更对我的胃口啊！难点是：怎么能知道下方的DOM元素呢？呃，其实一点也不难。因为在我们这个场景里，这两个元素必然是相临的关系： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/9a88cc16248548fc8bfe5cb0cef164a5~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1526\&h=820\&s=261979\&e=png\&b=ffffff) 所以，代码也很容易写出来了： ```tsx const exampleRef = useRef(null); const codeRef = useRef(null); useEffect(() => { const parent = exampleRef.current?.parentElement!; const index = [...parent.childNodes].findIndex((node) => node === exampleRef.current ); const next = parent.childNodes[index + 1]; codeRef.current!.appendChild(next); }, []); return (

); ``` 效果如下： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/dbed683977f14f5abb183827ffea6767~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=2516\&h=934\&s=292638\&e=png\&b=f7f9fc) 哈！ ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/7e40c7d443b0464c9f60234e007de17c~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=240\&h=240\&s=64020\&e=gif\&b=d4bdac) 呃，现实中并没有这么光鲜啦。事实上我是走了弯路滴。首先，我给代码块添加了一个`id`属性： ```tsx import React, { type FC } from 'react'; import Code from "dumi/theme-default/builtins/SourceCode"; import { type Language } from 'prism-react-renderer'; interface SourceCodeProps { id?: string; children: string; lang: Language; highlightLines?: number[]; } const SourceCode: FC = (props) => { const { id } = props; if (id) { return


  }
  return ;
};

export default SourceCode;
```

其次，写脚本注入了以下模板：

````markdown
```jsx
/**
 * inline: false
 */
import { ThingjsExample } from 'thingjs-docs';
export default () => {
  const content = `<%- replacedCode -%>`;
  return ;
};
```

```ts | #<%= scriptId %>
<%- code -%>
```
````

最终生成了这样的文件：

````markdown
```jsx
/**
 * inline: false
 */
import { ThingjsExample } from 'thingjs-docs';
export default () => {
  const content = `
const app = new THING.App();

await app.load("./assets/scenes/campus/campus.gltf");
`;
  return ;
};
```

```ts | #THINGJS_SCRIPT_52
const app = new THING.App();

await app.load("./assets/scenes/campus/campus.gltf");
```
````

这样，下方的代码块就有了`id`了。

![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/ad72e7dd0e3a400292803f7c23437896~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=748\&h=162\&s=35474\&e=png\&b=ffffff)

再在`jsx`中将它移动到右侧代码块：

```tsx
useEffect(() => {
  if (!scriptId) {
    return;
  }
  const script = document.getElementById(scriptId) as HTMLDivElement;
  if (!script) {
    console.warn(`script with id ${scriptId} not found`);
    return;
  }
  codeRef.current!.appendChild(script);
}, []);
```

搞复杂了！这圈子绕的，有些远了啊！

## 总结

本文详细介绍了我在使用 dumi 展现3D示例过程中遇到的挑战和解决方案。

我们的文档网站以Markdown为主，没有动态内容，API和示例部分使用`iframe`嵌套，需要优化搜索功能。这时，我们有三种方案处理：

1.  现有功能 +`Elastic Search`（ES）优化。
2.  现有功能 +`algolia`等第三方搜索服务。
3.  使用 `dumi` 的纯前端方案。

最终选择了第三种方案，因为 `dumi` 有以下优点：

1.  全文搜索，省去了后端服务。
2.  UI 设计更美观，支持响应式布局、暗黑模式、多语言等
3.  可扩展 Markdown 的自定义组件。

但在实际调研过程中，遇到了示例部分的挑战。

1.  示例部分需要实现左右布局，但还要兼顾代码块的全文搜索。
2.  `dumi`搜索仅包含静态 Markdown 部分，动态 React 组件无法被搜索。

这时衍生了以下解决方案：

1.  魔改 dumi 源码 Hook，想办法将代码块动态注入搜索源。缺点是需要注入研究dumi搜索机制，较为复杂。
2.  将代码块批量生成Markdown文件，上部分是React组件，呈现3D效果，下部分是代码块。缺点是只有上下布局。
3.  在第二个方案基础上，上部分组件同时呈现3D和代码，添加元属性隐藏掉下方的代码块，仅供搜索使用。
4.  将示例组件的代码块乾坤大挪移，上部分仍是左右布局，但右侧是空的div，在组件挂载后，将下方的代码块移动到右侧。这种方法简单而有效，它既复用了`dumi`的现有组件，同时保证了搜索功能的完整性。

虽然最终的方案看起来平平无奇，但不失为一种有趣的思路。希望能对大家有所启发！