docs: improve guide and add env config (umijs#1697)

* docs: add version select * docs: describe conventional files * docs: add env config doc * docs: improve i18n doc * docs: improve page tab doc * docs: improve write demo doc * docs: improve 2-level nav preview image
Wxh16144-forks · May 29, 2023 · ce91874 · ce91874
1 parent 494dcfa
commit ce91874
Show file tree

Hide file tree

Showing 14 changed files with 181 additions and 73 deletions.
diff --git a/.dumi/theme/slots/HeaderExtra/index.tsx b/.dumi/theme/slots/HeaderExtra/index.tsx
@@ -0,0 +1,33 @@
+import { ReactComponent as IconDown } from '@ant-design/icons-svg/inline-svg/outlined/down.svg';
+import React, { type FC } from 'react';
+
+const HeaderExtra: FC = () => {
+  return (
+    <div
+      className="dumi-default-lang-select"
+      style={{
+        borderInlineStart: '1px solid #d0d5d8',
+        marginInlineStart: 15,
+        paddingInlineStart: 5,
+      }}
+    >
+      <select
+        style={{ paddingTop: 1, paddingBottom: 1 }}
+        value={process.env.DUMI_VERSION}
+        onChange={(e) => {
+          if (e.target.value !== process.env.DUMI_VERSION) {
+            window.open('https://v1.d.umijs.org/', '_blank');
+          }
+        }}
+      >
+        <option value={process.env.DUMI_VERSION}>
+          {process.env.DUMI_VERSION}
+        </option>
+        <option value="1.x">1.x</option>
+      </select>
+      <IconDown />
+    </div>
+  );
+};
+
+export default HeaderExtra;
diff --git a/.dumirc.ts b/.dumirc.ts
@@ -1,4 +1,5 @@
 import { defineConfig } from './dist';
+import { version } from './package.json';
 
 export default defineConfig({
   html2sketch: {},
@@ -7,6 +8,9 @@ export default defineConfig({
   ],
   autoAlias: false,
   outputPath: 'docs-dist',
+  define: {
+    'process.env.DUMI_VERSION': version,
+  },
   themeConfig: {
     hd: { rules: [] },
     rtl: true,

diff --git a/docs/config/env.md b/docs/config/env.md
@@ -0,0 +1,7 @@
+# 环境变量配置
+
+<embed src="../.upstream/env-config.md"></embed>
+
+### DUMI_CACHE
+
+默认会将框架的高消耗执行结果（例如编译 Markdown 文件）持久化存储到本地，该结果会在二次执行时被选择性复用以提升框架运行速度，设置为 `none` 时可以禁用该行为，通常用于开发自定义 Markdown 插件的调试环节。
diff --git a/docs/config/markdown.md b/docs/config/markdown.md
@@ -92,7 +92,7 @@ title: 配置页面标题
 :::warning
 二级导航为 dumi v2.2 的新增特性，由于二级导航特性会影响主题 API 的行为，为了保证对存量项目及主题包的向前兼容，dumi 仅在项目 `devDependencies` 中声明的 dumi 版本号大于等于 `2.2.0`（例如 `^2.2.0`）时才会启用该特性
 
-如果你的项目使用了三方主题包，能否使用二级导航则取决于主题包是否适配该特性，dumi 会依据主题包 `peerDependencies` 中声明的 dumi 版本作为判断依据
+如果你的项目使用了三方主题包，能否使用二级导航则取决于主题包是否适配该特性，dumi 会将主题包 `peerDependencies` 中声明的 dumi 版本作为判断依据
 :::
 
 <!-- 2-level nav warning end -->

diff --git a/docs/guide/conventional-routing.md b/docs/guide/conventional-routing.md
@@ -71,7 +71,15 @@ docs
 
 根据一级导航的规则，上面所有的 Markdown 必然都归属于 `Platforms` 导航，但同时它们还会分别归属于 `Pc` 和 `Mobile` 这两个二级导航，这是因为这些路由路径除了拥有共同的 `/platforms` 前缀外，还拥有各自的二级路径前缀，即 `/pc` 和 `/mobile`，二级导航的 UI 效果如下：
 
-<img src="https://gw.alipayobjects.com/zos/bmw-prod/85a246ef-5f74-4f70-97fe-f6b40968e0bf/lhpzbiod_w288_h232.jpeg" width="140" />
+<style>
+  #two-level-nav-preview {
+    background-image: url(https://gw.alipayobjects.com/zos/bmw-prod/f1bc7aba-c1b5-41a1-bb00-7a713a6c791f/li8agnz8_w312_h252.jpeg);
+  }
+  [data-prefers-color="dark"] #two-level-nav-preview {
+    background-image: url(https://gw.alipayobjects.com/zos/bmw-prod/2ba687cd-4dd2-4a14-94df-38986a5beb0e/li8angg8_w312_h252.jpeg);
+  }
+</style>
+<div style="width: 156px; height: 126px; background-size: cover;" id="two-level-nav-preview"></div>
 
 二级导航的名称及顺序的默认规则与一级导航一致，类似的，我们也可以在该二级导航类目下**任一文档**的 Markdown 源文件头部通过 FrontMatter 指定，比如：
 

diff --git a/docs/guide/i18n.md b/docs/guide/i18n.md
@@ -7,15 +7,26 @@ order: 0
 
 # 多语言
 
-让文档站点变成多语言这件事，对 dumi 用户来说是开箱即用的。比如我们使用中文编写了 `docs/index.md` 作为站点的首页，现在希望增加站点的英文版本，只需要在 .dumirc.ts 里为 [locales](/config#locales) 配置增添一项 `en-US` 语言,并且创建一个带 `en-US` locale 后缀的同名 Markdown 文件即可：
+当我们想为文档站点增加多语言支持时，只需要在 `.dumirc.ts` 通过 [locales](../config/index.md#locales) 增加多语言配置，例如：
+
+```ts
+export default {
+  locales: [
+    { id: 'zh-CN', name: '中文' },
+    { id: 'en-US', name: 'EN' },
+  ],
+};
+```
+
+然后我们以约定式的形式创建多语言的 Markdown 文件即可实现多语言支持，例如：
 
 ```bash
 .
-├── docs
-│   ├── index.md        # 已有的中文版首页
-│   └── index.en-US.md  # 新创建的英文版首页
+└── docs
+    ├── index.md        # 已有的中文版首页
+    └── index.en-US.md  # 新创建的英文版首页
 ```
 
-这样一来，当用户访问 `www.example.com` 时 dumi 会渲染中文版首页，访问 `www.example.com/en-US` 时 dumi 会渲染英文版首页，对于其他页面也是一样的。
+此时，假定我们的网站域名是 `www.example.com`，那么访问 `www.example.com` 时则会渲染 `index.md` 的内容，访问 `www.example.com/en-US` 时则会渲染 `index.en-US.md` 的内容；同时，导航栏的右侧也会出现多语言切换的按钮（两种语言时）或下拉菜单（超过两种语言时），可供用户自由切换站点语言。
 
-在 dumi 的默认配置中，`zh-CN` 是默认语言，`en-US` 是第二种语言，如果你需要修改这个配置，比如修改默认语言、或者添加更多语言，请查看配置项 [locales](/config#locales)。
+更多关于多语言配置项的细节，可参考 [locales](../config/index.md#locales) 配置项。
diff --git a/docs/guide/page-tab.$tab-example.md b/docs/guide/page-tab.$tab-example.md
@@ -0,0 +1,5 @@
+---
+title: Tab 示例
+---
+
+这里是页面 Tab 的示例，内容在独立的 Markdown 中维护。
diff --git a/docs/guide/page-tab.md b/docs/guide/page-tab.md
@@ -5,36 +5,24 @@ order: 1
 
 # 页面 Tab
 
-dumi 支持组件页面的 Tab 自定义，分为以下两种方式
-
-## 约定式
+为了便于开发者更优雅地组织复杂文档，比如将 API、示例、设计规范等内容组合呈现，dumi 提供了开箱即用的约定式页面 Tab 特性，以该篇文档为例：
 
 ```bash
 .
-├── src
-│   ├── Foo
-│   │   ├── index.md
-│   │   └── index.$tab-api.md  # Tab 内容
+└── docs
+    └── guide
+        ├── page-tab.md
+        └── page-tab.$tab-example.md  # Tab 示例内容
 ```
 
-约定式就是不用手写配置，通过判断 md 文件命名是否带有 `$tab-` ，此文件将作为 Tab 的内容部分，如上所示，`index.$tab-api.md` 会作为 `index.md` 的 Tab 呈现。此处 `api` 作为 Tab 的 key 值，如果需要配置 Tab 标题，可以使用 FrontMatter 来定义。
-
-## 通过插件注册
-
-为了便于插件对 Tab 进行统一扩展，dumi 还提供了插件 API : `addContentTab` ，我们可以使用它为指定路由添加 Tab。
-
-```ts
-// plugin.ts
-import { IApi } from 'dumi';
+dumi 约定同名 Markdown 文件的 `$tab-{key}` 修饰符该文档的 Tab 内容，如上所示，`page-tab.$tab-example.md` 会作为 `page-tab.md` 的 Tab 呈现。此处 `example` 作为 Tab 的 key 值，如果需要配置 Tab 标题，可以使用 FrontMatter 来定义，用法[同普通文档](../config/markdown.md)：
 
-export default (api: IApi) => {
-  api.addContentTab(() => ({
-    key: 'test',
-    title: '标题',
-    component: require.resolve('./a.tsx'),
-    test: /^\/components\//,
-  }));
-};
+```md
+---
+title: Tab 示例
+---
 ```
 
-`component` 放入我们自定义的 Tab 内容，`test` 可以写入正则来匹配路由，`title` 为我们自定义 Tab 标题，如果需要配置国际化标题，可以通过 [modifyTheme](/plugin/api#modifytheme) API 来添加 locales 数据，然后配置 [titleIntlId](/plugin/api#addcontenttab) 关联对应的 key 来实现国际化。这样我们就实现了为 `/componets` 下的路由页面添加自定义 Tab。
+如此一来，我们就能得到和当前页面一样的 Tab 效果。
+
+如果你是 dumi 的主题包或插件开发者，还可以通过插件 API 来为指定路由添加 Tab，具体用法请参考 [插件 API - addContentTab](../plugin/api.md#addcontenttab)。
diff --git a/docs/guide/project-structure.md b/docs/guide/project-structure.md
@@ -6,7 +6,9 @@ order: 1
 
 # 目录结构
 
-一个普通的、使用 dumi 做研发的组件库目录结构大致如下：
+## 基础结构
+
+如果你是通过 `create-dumi` 创建的 React 脚手架（`React` 选项），那么生成的目录结构大致如下：
 
 <Tree>
   <ul>
@@ -19,12 +21,8 @@ order: 1
           <small>组件库文档首页</small>
         </li>
         <li>
-          guide
-          <small>组件库其他文档路由表（示意）</small>
-          <ul>
-            <li>index.md</li>
-            <li>help.md</li>
-          </ul>
+          guide.md
+          <small>组件库其他文档路由（示意）</small>
         </li>
       </ul>
     </li>
@@ -33,17 +31,13 @@ order: 1
       <small>组件库源码目录</small>
       <ul>
         <li>
-          Button
+          Foo
           <small>单个组件</small>
           <ul>
             <li>
               index.tsx
               <small>组件源码</small>
             </li>
-            <li>
-              index.less
-              <small>组件样式</small>
-            </li>
             <li>
               index.md
               <small>组件文档</small>
@@ -58,15 +52,50 @@ order: 1
     </li>
     <li>
       .dumirc.ts
-      <small>dumi 配置文件</small>
+      <small>dumi 的配置文件</small>
     </li>
     <li>
       .fatherrc.ts
-      <small>father-build 的配置文件，用于组件库打包</small>
+      <small>father 的配置文件，用于组件库打包</small>
     </li>
   </ul>
 </Tree>
 
-如果是单纯的文档站点、不包含组件源码，忽略上面的 `src` 目录结构即可。
+如果你创建的是静态站点（`Static Site` 选项），那么忽略上面的 `src` 目录结构即可。
+
+## 其他目录约定
+
+:::warning
+这些约定仅作用于组件库文档，不会对组件库源码构建产生任何影响，请勿基于这些约定来实现特定的组件库功能（比如为组件库添加全局样式）。
+:::
+
+### 全局样式
+
+约定如下两个路径为文档添加全局样式：
+
+1. 创建 `.dumi/global.(less|sass|scss|css)`：适用于单纯的全局样式新增
+2. 创建 `.dumi/overrides.(less|sass|scss|css)`：适用于覆盖 dumi 默认主题或三方主题包的样式，该文件中的规则会自动提升一层优先级确保覆盖生效
+
+### 全局脚本
+
+约定 `.dumi/global.(js|jsx|ts|tsx)` 为全局脚本文件，适用于要在全局添加自定义逻辑的场景（比如监控运行时错误并上报）。
+
+### 运行时配置
+
+约定 `.dumi/app.(js|jsx|ts|tsx)` 为运行时配置文件，适用于修改框架运行时配置的场景。
+
+### 加载组件
+
+约定 `.dumi/loading.(js|jsx|ts|tsx)` 为全局 loading 组件；dumi 2 默认按路由对产物拆包，切换页面时需要等待异步 chunk 加载完成后才能呈现，可通过该组件来为用户展示自定义加载动画。
+
+### 404 页面
+
+约定 `.dumi/pages/404.(js|jsx|ts|tsx)` 为自定义 404 页面。
+
+### favicon
+
+约定 `.dumi/favicon.(ico|gif|png|jpg|jpeg|svg|avif|webp)` 为站点 favicon 图标，当存在任一后缀文件时，dumi 将会自动在 HTML 中插入对应的 `link` 标签以应用 favicon；你也可以通过 [favicons](../config/index.md#favicons) 配置项来手动指定 favicon。
+
+### 临时文件目录
 
-注意，此处仅对目录结构做说明，如果要初始化一个 dumi 项目，建议直接使用 `create-dumi` 的脚手架进行创建。
+约定 `.dumi/tmp*` 为框架的临时文件，这些文件由 dumi 在编译过程中自动生成，**请勿直接修改或在代码中引入它们**。
diff --git a/docs/guide/write-demo.md b/docs/guide/write-demo.md
@@ -37,25 +37,6 @@ export default () => <h1>Hello dumi!</h1>;
 
 但是在 markdown 代码块中编写代码会失去类型提示和校验，不能像直接在 `tsx` 中那样丝滑，因此我们推荐使用 VSCode 插件 [TS in Markdown](https://github.com/Dali-Team/vscode-ts-in-markdown)。
 
-#### 在 demo 中引入组件
-
-dumi 有一个非常重要的原则——**开发者应该像用户一样使用组件**。
-
-如何理解？假设我们正在研发的组件库 NPM 包名叫做 `hello-dumi`，我们正在为其中的 `Button` 组件编写 demo，下面列举出引入组件的正确方式及错误示例：
-
-```jsx | pure
-// 正确示例
-import { Button } from 'hello-dumi';
-
-// 错误示例，用户不知道 Button 组件是哪里来的
-import Button from './index.tsx';
-import Button from '@/Button/index.tsx';
-```
-
-当我们的每个 demo 都秉持这一原则时，意味着我们写出的 demo，不仅可以用来调试组件、编写文档，还能被用户直接拷贝到项目中使用。
-
-也许你会有疑问，研发阶段的组件库源代码尚未发布成 NPM 包，怎么才能成功引入组件？无需担心，dumi 会为我们自动建立组件库 NPM 包 -> 组件库源代码的映射关系。
-
 #### 不渲染代码块
 
 如果我们希望某段 `jsx`/`tsx` 代码块被渲染为源代码，可以使用 `pure` 修饰符告诉 dumi：
@@ -78,6 +59,8 @@ import Button from '@/Button/index.tsx';
 
 <code src="./demos/cols.tsx"></code>
 
+#### 本地跳过解析
+
 为了方便调试，你可以像 Jest 一样对 `<code />` 标签添加 `skip` 或 `only` 标识（仅在开发环境下有效）以跳过解析，例如：
 
 ```html
@@ -87,6 +70,25 @@ import Button from '@/Button/index.tsx';
 <code src="./demos/baz.tsx"></code>
 ```
 
+### 如何引入组件
+
+dumi 有一个非常重要的原则——**开发者应该像用户一样使用组件**。
+
+如何理解？假设我们正在研发的组件库 NPM 包名叫做 `hello-dumi`，我们正在为其中的 `Button` 组件编写 demo，下面列举出引入组件的正确方式及错误示例：
+
+```jsx | pure
+// 正确示例
+import { Button } from 'hello-dumi';
+
+// 错误示例，用户不知道 Button 组件是哪里来的
+import Button from './index.tsx';
+import Button from '@/Button/index.tsx';
+```
+
+当我们的每个 demo 都秉持这一原则时，意味着我们写出的 demo，不仅可以用来调试组件、编写文档，还能被用户直接拷贝到项目中使用。
+
+也许你会有疑问，研发阶段的组件库源代码尚未发布成 NPM 包，怎么才能成功引入组件？无需担心，dumi 会为我们自动建立组件库 NPM 包 -> 组件库源代码的映射关系；如果你的项目是 monorepo，请使用 [`monorepoRedirect` 配置项](../config/index.md#monoreporedirect)来自动建立映射关系，同时也需要在 `tsconfig.json` 中为每个子包配置正确的 `paths` 确保类型可以正确解析。
+
 ## 控制 demo 渲染
 
 dumi 提供了一些 FrontMatter 属性，以满足不同的 demo 渲染需求，在**源代码顶部**配置即可：

diff --git a/docs/index.md b/docs/index.md
@@ -2,10 +2,7 @@
 title: dumi - 为组件研发而生的静态站点框架
 hero:
   title: dumi
-  description: |
-    为组件研发而生的静态站点框架
-    <br />
-    <small style="opacity: 0.7;">v1 文档请访问 <a href="https://v1.d.umijs.org" style="color: #1677ff;">v1.d.umijs.org</a></small>
+  description: 为组件研发而生的静态站点框架
   actions:
     - text: 立即上手
       link: /guide

diff --git a/docs/plugin/api.md b/docs/plugin/api.md
@@ -32,7 +32,8 @@ api.addContentTab(() => ({
    */
   title?: string;
   /**
-   * tab 名称文案国际化，通过传入国际化文案 key 来实现。优先级高于 name 配置项
+   * tab 名称文案国际化，通过传入国际化文案 key 来实现。优先级高于 title 配置项
+   * 可通过 api.modifyTheme 来配置国际化文案 key 对应的文案
    */
   titleIntlId?: string;
   /**

diff --git a/scripts/sync-from-umi.js b/scripts/sync-from-umi.js
@@ -255,6 +255,28 @@ const FILE_LIST = [
       // },
     ],
   },
+  {
+    localname: 'env-config.md',
+    upstream:
+      'https://cdn.jsdelivr.net/gh/umijs/umi@4/docs/docs/guides/env-variables.md',
+    actions: [
+      // remove head content
+      { type: 'slice', value: [1] },
+      // remove unnecessary section
+      ...['DID_YOU_KNOW'].map((option) => ({
+        type: 'replace',
+        value: [new RegExp(`(?:^|[\r\n])### ${option}[^]+?([\r\n]#|$)`), '$1'],
+      })),
+      // replace umi to dumi
+      { type: 'replace', value: [/UMI/g, 'DUMI'] },
+      { type: 'replace', value: [/('|"|\s|`)umi/gi, '$1dumi'] },
+      // replace BABEL_CACHE to DUMI_CACHE
+      { type: 'replace', value: [/BABEL_CACHE/g, 'DUMI_CACHE'] },
+      { type: 'replace', value: [/\sbabel\s/g, ' dumi '] },
+      // replace config to .dumirc
+      { type: 'replace', value: [/config\./g, '.dumirc.'] },
+    ],
+  },
 ];
 
 if (!fs.existsSync(UMI_DOC_DIR)) {

diff --git a/tsconfig.json b/tsconfig.json
@@ -4,6 +4,7 @@
     "declaration": true,
     "skipLibCheck": true,
     "esModuleInterop": true,
+    "resolveJsonModule": true,
     "jsx": "react",
     "baseUrl": "./",
     "paths": {