From 29d93dcc6b0d984161667d64b589bc0350feb5ab Mon Sep 17 00:00:00 2001 From: Timeless0911 <1604889533@qq.com> Date: Tue, 2 Apr 2024 13:35:38 +0800 Subject: [PATCH] feat: support subpage overview --- .changeset/polite-swans-reply.md | 5 +++ .../en/guide/default-theme/overview-page.mdx | 42 +++++++++++++++++++ .../zh/guide/default-theme/overview-page.mdx | 42 +++++++++++++++++++ .../src/components/Overview/index.tsx | 28 ++++++++++++- 4 files changed, 115 insertions(+), 2 deletions(-) create mode 100644 .changeset/polite-swans-reply.md diff --git a/.changeset/polite-swans-reply.md b/.changeset/polite-swans-reply.md new file mode 100644 index 000000000..90c1e7f83 --- /dev/null +++ b/.changeset/polite-swans-reply.md @@ -0,0 +1,5 @@ +--- +"@rspress/theme-default": minor +--- + +feat: support subpage overview diff --git a/packages/document/docs/en/guide/default-theme/overview-page.mdx b/packages/document/docs/en/guide/default-theme/overview-page.mdx index e3903fbfa..c8840a0d1 100644 --- a/packages/document/docs/en/guide/default-theme/overview-page.mdx +++ b/packages/document/docs/en/guide/default-theme/overview-page.mdx @@ -58,3 +58,45 @@ At the same time, the file `api/theme/_meta.json` has the following content: In the above configuration, the final preview page will generate a group called `Theme`, which contains the h1, h2 titles of two articles: `component.md(x)` and `utils.md(x)`. Of course, you can also refer to the config of the `Theme` group to add more groups. If you want to control the minimum title displayed in the overview page, you can configure it through `overviewDepth` config in `_meta.json`, which defaults to h2. + +If you want to generate a sub-preview page under `theme`, there are two ways: + +1. Create a new file `theme.md` with the same name in the parent directory of `theme` and configure the frontmatter of `overview: true`. + +```bash +├── docs +│ ├── index.md +│ ├── api +│ │ ├── index.md +│ │ ├── theme.md +│ │ ├── theme +│ │ │ ├── component.mdx +│ │ │ ├── utils.mdx +//... +``` + +2. Create a new `index.md` in the `theme` directory and configure the frontmatter of `overview: true`. + +```bash +├── docs +│ ├── index.md +│ ├── api +│ │ ├── index.md +│ │ ├── theme +│ │ │ ├── index.md +│ │ │ ├── component.mdx +│ │ │ ├── utils.mdx +//... +``` + +Then configure `theme/_meta.json` as follows: + +```json +[ + { + "type": "file", + "name": "index", + "label": "Overview" + } +] +``` diff --git a/packages/document/docs/zh/guide/default-theme/overview-page.mdx b/packages/document/docs/zh/guide/default-theme/overview-page.mdx index 3dead6eab..74b6b9758 100644 --- a/packages/document/docs/zh/guide/default-theme/overview-page.mdx +++ b/packages/document/docs/zh/guide/default-theme/overview-page.mdx @@ -58,3 +58,45 @@ overview: true 在如上的配置中，最后预览页会生成一个 `Theme` 的分组，这个分组里面包含 `component.md(x)` 和 `utils.md(x)` 两篇文章的 h1、h2 标题。当然，你也可以参考 `Theme` 分组的配置，添加更多的分组。 如果要控制在预览页中展示的最小标题，可以通过 `_meta.json` 中的 `overviewDepth` 配置，默认为 h2。 + +如果要在 `theme` 下同样生成一个子预览页，有以下两种方式： + +1. 在 `theme` 的上级目录新建一个同名文件 `theme.md`，配置 `overview: true` 的 frontmatter。 + +```bash +├── docs +│ ├── index.md +│ ├── api +│ │ ├── index.md +│ │ ├── theme.md +│ │ ├── theme +│ │ │ ├── component.mdx +│ │ │ ├── utils.mdx +// ... +``` + +2. 在 `theme` 目录新建一个 `index.md`，配置 `overview: true` 的 frontmatter。 + +```bash +├── docs +│ ├── index.md +│ ├── api +│ │ ├── index.md +│ │ ├── theme +│ │ │ ├── index.md +│ │ │ ├── component.mdx +│ │ │ ├── utils.mdx +// ... +``` + +然后配置 `theme/_meta.json` 如下： + +```json +[ + { + "type": "file", + "name": "index", + "label": "Overview" + } +] +``` diff --git a/packages/theme-default/src/components/Overview/index.tsx b/packages/theme-default/src/components/Overview/index.tsx index 89ebf422c..cc4bf270b 100644 --- a/packages/theme-default/src/components/Overview/index.tsx +++ b/packages/theme-default/src/components/Overview/index.tsx @@ -56,11 +56,35 @@ export function Overview(props: { } return ''; }; + const findItemByRoutePath = (items, routePath, originalItems) => { + for (const item of items) { + if (item.link === routePath) { + return [item]; + } + if (item.items) { + const foundItem = findItemByRoutePath( + item.items, + routePath, + originalItems, + ); + if (foundItem) { + return foundItem; + } + } + } + return originalItems; + }; const { pages } = siteData; const overviewModules = pages.filter(page => subFilter(page.routePath)); - const { items: overviewSidebarGroups } = useSidebarData() as { + let { items: overviewSidebarGroups } = useSidebarData() as { items: (NormalizedSidebarGroup | SidebarItem)[]; }; + overviewSidebarGroups = findItemByRoutePath( + overviewSidebarGroups, + routePath, + overviewSidebarGroups, + ); + function normalizeSidebarItem( item: SidebarItem | SidebarDivider | NormalizedSidebarGroup, sidebarGroup?: NormalizedSidebarGroup, @@ -121,7 +145,7 @@ export function Overview(props: { ] : []), ]; - }, [overviewSidebarGroups]); + }, [overviewSidebarGroups, routePath]); return (