fix(plugin-docs,theme): refactor docs plugin routes and component tree #7966

slorber · 2022-08-17T18:00:19Z

Breaking changes

This refactor significantly changes the docs theme component tree. If you swizzled @theme/DocPage, or doc tags pages, you will likely need to upgrade your theme code a bit.

The tree of theme components rendering doc routes changed from:

Root
├── @theme/DocPage
│   └── @theme/DocPage/Layout
│       ├── @theme/DocPage/Layout/Sidebar
│       └── @theme/DocPage/Layout/Main
│           ├── @theme/DocCategoryGeneratedIndexPage
│           └── @theme/DocItem
├── @theme/DocTagsListPage
└── @theme/DocTagDocListPage

to this new structure

Root
└── @theme/DocsRoot
    └── @theme/DocVersionRoot
        ├── @theme/DocRoot
        │   └── @theme/DocRoot/Layout
        │       ├── @theme/DocRoot/Layout/Sidebar
        │       └── @theme/DocRoot/Layout/Main
        │           ├── @theme/DocCategoryGeneratedIndexPage
        │           └── @theme/DocItem
        ├── @theme/DocTagsListPage
        └── @theme/DocTagDocListPage

@theme/DocPage has been renamed to @theme/DocRoot
@theme/DocRoot (renamed) does not receive a versionMetadata prop anymore. The new @theme/DocVersionRoot receives it (upper in the tree), and makes it available in its subtree with the useDocsVersion() hook.
@theme/DocRoot (renamed), @theme/DocTagsListPage and @theme/DocTagDocListPage do not apply <Layout> anymore: it's applied in @theme/DocsLayout (parent of all docs plugin routes)
option docPageLayoutComponent has been renamed to docRootComponent

Note there's a clear distinction between:

@theme/DocsRoot: top-level parent layout component that wraps every docs plugin routes (all versions, docs, generated index, docs tags pages...) and apply the <Layout> globally
@theme/DocRoot: single doc layout, responsible for displaying the docs sidebar alongside the docs content (markdown or category generated index)

Motivation

All the versioned docs pages should have a shared parent layout page. This prevents unmounting/remounting the layout when navigating across docs pages, category-generated index pages, tags pages, and even across versions.

New docs plugin options:

docsRootComponent: the component that wraps every route of a single doc plugin instance
docVersionRootComponent: the component that wraps every route of a specific doc version

With this refactor, tags-related pages are able to use the useDocsVersion() hook.

Also fixes a bug in the core route sorting algorithm which was not really recursive.

Test Plan

unit tests + preview

Test links

Prod and deploy preview should look exactly the same.

Doc:

Tags list:

Tag page:

netlify · 2022-08-17T18:06:05Z

✅ [V2]

Name	Link
🔨 Latest commit	`5f53573`
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/62fe56e8c55bc30007836c08
😎 Deploy Preview	https://deploy-preview-7966--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

github-actions · 2022-08-17T18:06:38Z

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟢 90	🟢 98	🟢 100	🟢 100	🟠 80	Report
/docs/installation	🟠 79	🟢 100	🟢 100	🟢 100	🟢 90	Report

github-actions · 2022-08-17T18:17:59Z

Size Change: +592 B (0%)

Total Size: 814 kB

Filename	Size	Change
`website/build/assets/js/main.********.js`	609 kB	+592 B (0%)

ℹ️ View Unchanged

Filename	Size
`website/.docusaurus/globalData.json`	52.5 kB
`website/build/assets/css/styles.********.css`	111 kB
`website/build/index.html`	40.8 kB

_{compressed-size-action}

Josh-Cena · 2022-08-18T08:47:08Z

Does this supercede #6823?

slorber

Ready to review 👍

slorber · 2022-08-18T09:04:59Z

packages/docusaurus-plugin-content-docs/src/routes.ts

+export async function createAllRoutes(
+  param: CreateAllRoutesParam,
+): Promise<void> {
+  const versionRoutes = await buildVersionsRoutes(param);
+  versionRoutes.forEach((versionRoute) => param.actions.addRoute(versionRoute));
+}


I'd like to move all side-effects here. Ideally our route def API should be improved so that we don't need anymore to use actions.createData() => we should be able to test this route building more easily

slorber · 2022-08-18T09:06:17Z

packages/docusaurus-theme-classic/src/theme/DocPage/Layout/index.tsx

@@ -19,7 +18,7 @@ export default function DocPageLayout({children}: Props): JSX.Element {
  const sidebar = useDocsSidebar();
  const [hiddenSidebarContainer, setHiddenSidebarContainer] = useState(false);
  return (
-    <Layout wrapperClassName={styles.docsWrapper}>


Layout moved upper in the tree: Layout shouldn't unmount/remount when navigating from a doc page to a tag page for example

slorber · 2022-08-18T09:10:09Z

packages/docusaurus-theme-classic/src/theme/DocVersionPage/index.tsx

+        tag={docVersionSearchTag(version.pluginId, version.version)}
+      />
+      <PageMetadata>
+        {version.noIndex && <meta name="robots" content="noindex, nofollow" />}


fixes the limitation described in #7963, because version noIndex is now also applied to tag pages

slorber · 2022-08-18T09:14:53Z

packages/docusaurus/src/server/plugins/routeConfig.ts

@@ -63,6 +63,8 @@ export function sortConfig(
  });

  routeConfigs.forEach((routeConfig) => {
-    routeConfig.routes?.sort((a, b) => a.path.localeCompare(b.path));
+    if (routeConfig.routes) {
+      sortConfig(routeConfig.routes, baseUrl);


unrelated bug in route sorting algorithm: subroutes should be sorted recursively

necessary to make this PR work otherwise /test/docs/ subroute would appear before test/docs/tag/xyz and it fails

slorber · 2022-08-18T11:32:49Z

packages/docusaurus-plugin-content-docs/src/__tests__/options.test.ts

+      docsRootComponent: '@theme/DocsRoot',
+      docVersionRootComponent: '@theme/DocVersionRoot',
+      docRootComponent: '@theme/DocRoot',


New Root theme component we decided with @Josh-Cena .

@theme/DocPage becomes @theme/DocRoot

Hierarchy is: @theme/DocsRoot > @theme/DocVersionRoot > @theme/DocRoot

Josh-Cena

On https://deploy-preview-7966--docusaurus-2.netlify.app/docs/tags/:

NotFound renders Layout already

slorber · 2022-08-18T12:52:51Z

Thanks, good catch 😅 wonder how I'll fix that

Josh-Cena · 2022-08-18T13:22:59Z

Can it be a prop in NotFound to not render Layout?

slorber added 4 commits August 17, 2022 17:35

stable iso refactor of docs routes

827924f

move tags under version route

da3cbe9

fix routeConfig algo not recursive

03cc683

stable refactor

f560724

slorber added pr: breaking change Existing sites may not build successfully in the new version. Description contains more details. pr: bug fix This PR fixes a bug in a past release. labels Aug 17, 2022

slorber requested review from lex111 and Josh-Cena as code owners August 17, 2022 18:00

facebook-github-bot added the CLA Signed Signed Facebook CLA label Aug 17, 2022

slorber marked this pull request as draft August 17, 2022 18:03

prettier

925495a

slorber added 6 commits August 18, 2022 10:54

update doc

5878a16

remove useless sortRoutes

e5b60b3

add missing await useful for try/catch

ac57a60

refactor plugin options and component names

2c5c28e

better doc

42d7ebb

update snapshot + complete comment

e74837b

slorber commented Aug 18, 2022

View reviewed changes

slorber mentioned this pull request Aug 18, 2022

feat(docs): allow to configure noIndex per doc version #7963

Merged

update snapshot

53f86dc

slorber mentioned this pull request Aug 18, 2022

refactor(content-docs): add tags route as a subroute of version route #6823

Closed

slorber marked this pull request as ready for review August 18, 2022 11:48

Josh-Cena requested changes Aug 18, 2022

View reviewed changes

Fix notfound docs double-layout issue

ca177b3

slorber added 2 commits August 18, 2022 16:34

test commit

9ae5d53

test commit

5f53573

slorber merged commit 3b9b497 into main Aug 18, 2022

slorber deleted the slorber/docs-routes-refactor branch August 18, 2022 15:55

slorber mentioned this pull request Aug 18, 2022

Using docs routeBasePath="/", navbar version dropdown displays incorrect version on "/" #7974

Open

7 tasks

slorber mentioned this pull request Feb 24, 2023

Docs layout issue: content container does not grow to take all the available space #8369

Closed

7 tasks

slorber mentioned this pull request Jun 15, 2023

chore: v3.0.0-alpha.0 release #9072

Merged

slorber mentioned this pull request Sep 15, 2023

chore: v3.0.0-beta.0 release #9311

Merged

This was referenced Oct 19, 2023

chore: v3.0.0-rc.0 release #9418

Merged

chore: v3.0.0-rc.1 release #9453

Merged

tukib mentioned this pull request Nov 1, 2023

Upgrade Docusaurus from ^2.4.3 to ^3.0.0 comcode-org/hackmud_wiki#34

Closed

3 tasks

egdmrsy mentioned this pull request Nov 20, 2023

Bump dependency versions and handle breaking changes openkfw/trubudget-website#88

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(plugin-docs,theme): refactor docs plugin routes and component tree #7966

fix(plugin-docs,theme): refactor docs plugin routes and component tree #7966

slorber commented Aug 17, 2022 •

edited

netlify bot commented Aug 17, 2022 •

edited

github-actions bot commented Aug 17, 2022 •

edited

github-actions bot commented Aug 17, 2022 •

edited

Josh-Cena commented Aug 18, 2022

slorber left a comment

slorber Aug 18, 2022

slorber Aug 18, 2022

slorber Aug 18, 2022

slorber Aug 18, 2022

slorber Aug 18, 2022

Josh-Cena left a comment •

edited

slorber commented Aug 18, 2022

Josh-Cena commented Aug 18, 2022

fix(plugin-docs,theme): refactor docs plugin routes and component tree #7966

fix(plugin-docs,theme): refactor docs plugin routes and component tree #7966

Conversation

slorber commented Aug 17, 2022 • edited

Breaking changes

Motivation

Test Plan

Test links

netlify bot commented Aug 17, 2022 • edited

✅ [V2]

github-actions bot commented Aug 17, 2022 • edited

⚡️ Lighthouse report for the deploy preview of this PR

github-actions bot commented Aug 17, 2022 • edited

Josh-Cena commented Aug 18, 2022

slorber left a comment

Choose a reason for hiding this comment

slorber Aug 18, 2022

Choose a reason for hiding this comment

slorber Aug 18, 2022

Choose a reason for hiding this comment

slorber Aug 18, 2022

Choose a reason for hiding this comment

slorber Aug 18, 2022

Choose a reason for hiding this comment

slorber Aug 18, 2022

Choose a reason for hiding this comment

Josh-Cena left a comment • edited

Choose a reason for hiding this comment

slorber commented Aug 18, 2022

Josh-Cena commented Aug 18, 2022

slorber commented Aug 17, 2022 •

edited

netlify bot commented Aug 17, 2022 •

edited

github-actions bot commented Aug 17, 2022 •

edited

github-actions bot commented Aug 17, 2022 •

edited

Josh-Cena left a comment •

edited