Skip to content

Commit

Permalink
docs(module-doc): update options
Browse files Browse the repository at this point in the history
  • Loading branch information
10Derozan committed Feb 19, 2024
1 parent 9a7e17a commit 1b898a3
Show file tree
Hide file tree
Showing 2 changed files with 41 additions and 24 deletions.
27 changes: 17 additions & 10 deletions packages/document/module-doc/docs/en/guide/basic/use-module-doc.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ The sidebars corresponding in turn to the above file paths and routing paths are
### Configure sidebar

As shown in the figure above, the module documentation has automatically generated sidebars for file system routing, where the text of each column of the sidebar is determined by the file's first level title or directory name.
If you need to customize the sidebar, please use [_meta.json](https://rspress.dev/guide/basic/auto-nav-sidebar.html) or configure [sidebar](https://rspress.dev/api/config/config-theme.html#sidebar) directly.
If you need to customize the sidebar, please use [\_meta.json](https://rspress.dev/guide/basic/auto-nav-sidebar.html) or configure [sidebar](https://rspress.dev/api/config/config-theme.html#sidebar) directly.

:::info
If your document directory structure complies with internationalization, for example:
Expand Down Expand Up @@ -146,9 +146,9 @@ export default defineConfig({
modulePluginDoc({
/**
* Select the preview method
* @default web
* @default internal
*/
previewMode: 'mobile',
previewMode: 'iframe',
/**
* Select iframe position
* @default 'follow'
Expand All @@ -167,12 +167,12 @@ If you only want to change the way a particular `jsx` and `tsx` block is preview
// The content here will not be rendered
```

```jsx web
// Used to render desktop components
```jsx internal
// Used to render components in documentation
```

```jsx mobile
// Used to render mobile components
```jsx iframe
// Used to render components in iframe
```
````

Expand All @@ -186,6 +186,12 @@ If our demo is very complex, then it is recommended to write the demo separately
<code src="/path/demo.tsx"></code>
```

This also supports setting the preview method for each individual code block, for example:

```mdx
<code src="/path/demo.tsx" previewMode="iframe"></code>
```

## Using built-in components

The plugin implements some built-in components internally so that you can develop module documentation more easily.
Expand Down Expand Up @@ -398,10 +404,10 @@ type ParseToolOptions = {

### previewMode

- Type:`'mobile' | 'web'`
- Default: `'web'`
- Type:`'iframe' | 'internal'`
- Default: `'internal'`

In case of `web`, the component will be rendered directly in the page, otherwise it will be loaded through an iframe.
In case of `internal`, the component will be rendered directly in the page, otherwise it will be loaded through an iframe.

### deprecated: languages

Expand All @@ -417,6 +423,7 @@ or directly configure [sidebar](https://rspress.dev/api/config/config-theme.html
:::

## Scripts

- `modern dev`: Start dev server for doc site.
- `modern build --platform`: Build doc site in production, by default output directories is `doc_build`.

Expand Down
38 changes: 24 additions & 14 deletions packages/document/module-doc/docs/zh/guide/basic/use-module-doc.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -55,10 +55,11 @@ docs
### 配置侧边栏

如上图所示,模块文档已经为文件系统路由自动生成了侧边栏,其中侧边栏每一栏的文本是由文件的一级标题或者目录名决定。
如果你需要自定义侧边栏,请使用 [_meta.json](https://rspress.dev/zh/guide/basic/auto-nav-sidebar.html) 或者直接配置 [sidebar](https://rspress.dev/zh/api/config/config-theme.html#sidebar)
如果你需要自定义侧边栏,请使用 [\_meta.json](https://rspress.dev/zh/guide/basic/auto-nav-sidebar.html) 或者直接配置 [sidebar](https://rspress.dev/zh/api/config/config-theme.html#sidebar)

:::info
如果你的文档目录结构是符合国际化的,例如:

```bash
docs
├── en
Expand All @@ -68,6 +69,7 @@ docs
├── button.mdx
├── index.mdx
```

你需要按照[国际化](https://rspress.dev/zh/guide/default-theme/i18n.html)章节,同时配置 `lang``locales`,否则模块自动生成的侧边栏不会处理 `zh``en` 这两个目录。
:::

Expand Down Expand Up @@ -139,9 +141,9 @@ export default defineConfig({
modulePluginDoc({
/**
* 选择预览方式
* @default web
* @default internal
*/
previewMode: 'mobile',
previewMode: 'iframe',
/**
* 设置 iframe 的位置
* @default 'follow'
Expand All @@ -160,12 +162,12 @@ export default defineConfig({
// 这里的内容不会被渲染
```

```jsx web
// 用来渲染桌面端组件
```jsx internal
// 内置在文档内容里渲染
```

```jsx mobile
// 用来渲染移动端组件
```jsx iframe
// 使用 iframe 渲染
```
````

Expand All @@ -179,6 +181,12 @@ export default defineConfig({
<code src="/path/demo.tsx"></code>
```

这同样支持单独设置代码块的预览方式,例如:

```mdx
<code src="/path/demo.tsx" previewMode="iframe"></code>
```

## 使用内置组件

插件内部实现了一部分内置组件,以便于你可以更轻松地开发模块文档。
Expand Down Expand Up @@ -245,15 +253,16 @@ export const Button = (props?: ButtonProps) => {};

:::warning
如果 Props 里使用了 React 的类型,你需要在 tsconfig.json 里添加 types ,否则会解析不到 React 命名空间下的类型。

```json
{
"compilerOptions": {
"types": ["react"],
},
"types": ["react"]
}
}
```
:::

:::

- `documentation`适用于工具库场景,用来解析 JSDoc 注释。

Expand Down Expand Up @@ -394,10 +403,10 @@ type ParseToolOptions = {

代码块预览方式。

- 类型:`'mobile' | 'web'`
- 默认值: `'web'`
- 类型:`'internal' | 'iframe'`
- 默认值: `'internal'`

`web`时,代码块内容将会直接渲染在页面中,反之将会通过 iframe 加载。
`internal`时,代码块内容将会直接渲染在页面中,反之将会通过 iframe 加载。

### deprecated: languages

Expand All @@ -408,11 +417,12 @@ type ParseToolOptions = {
### deprecated: useModuleSidebar

:::warning
从 MAJOR_VERSION.44.0 版本开始,内部实现了嗅探机制,请直接使用 [_meta.json](https://rspress.dev/zh/guide/basic/auto-nav-sidebar.html)
从 MAJOR_VERSION.44.0 版本开始,内部实现了嗅探机制,请直接使用 [\_meta.json](https://rspress.dev/zh/guide/basic/auto-nav-sidebar.html)
或者直接配置 [sidebar](https://rspress.dev/zh/api/config/config-theme.html#sidebar) 来实现自定义侧边栏。
:::

## 命令行

- `modern dev`: 启动文档站本地开发。
- `modern build --platform`: 构建生产环境产物。

Expand Down

0 comments on commit 1b898a3

Please sign in to comment.