Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(module-doc): update options #5400

Merged
merged 1 commit into from
Feb 19, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
Loading