From 3aa129d03dc48f89268bce4c1db4a9dab92e499a Mon Sep 17 00:00:00 2001 From: sebastienlorber Date: Thu, 5 May 2022 19:38:32 +0200 Subject: [PATCH 1/3] prepare beta 20 --- CHANGELOG.md | 27 +++ .../guides/docs/docs-markdown-features.mdx | 39 ---- .../markdown-features-headings.mdx | 57 ------ .../advanced/architecture.md | 0 .../advanced/client.md | 71 ++++++- .../advanced/index.md | 0 .../advanced/plugins.md | 2 +- .../advanced/routing.md | 4 +- .../advanced/ssg.md | 2 + .../api/docusaurus.config.js.md | 136 +++++++------ .../api/misc/_category_.yml | 2 + .../api/misc/create-docusaurus.md | 57 ++++++ .../api/misc/eslint-plugin/README.md | 74 +++++++ .../eslint-plugin/no-untranslated-text.md | 48 +++++ .../string-literal-i18n-messages.md | 50 +++++ .../api/misc/img/logger-demo.png | Bin 0 -> 94456 bytes .../version-2.0.0-beta.20/api/misc/logger.md | 67 +++++++ .../api/plugin-methods/README.md | 4 +- .../api/plugin-methods/_category_.yml | 0 .../plugin-methods/extend-infrastructure.md | 0 .../api/plugin-methods/i18n-lifecycles.md | 0 .../api/plugin-methods/lifecycle-apis.md | 16 +- .../api/plugin-methods/static-methods.md | 0 .../api/plugins/_category_.yml | 0 .../api/plugins/overview.md | 0 .../api/plugins/plugin-client-redirects.md | 0 .../api/plugins/plugin-content-blog.md | 2 +- .../api/plugins/plugin-content-docs.md | 85 +++++--- .../api/plugins/plugin-content-pages.md | 0 .../api/plugins/plugin-debug.md | 0 .../api/plugins/plugin-google-analytics.md | 0 .../api/plugins/plugin-google-gtag.md | 2 +- .../api/plugins/plugin-ideal-image.md | 0 .../api/plugins/plugin-pwa.md | 0 .../api/plugins/plugin-sitemap.md | 6 +- .../api/themes/_category_.yml | 0 .../api/themes/overview.md | 0 .../api/themes/theme-classic.md | 0 .../api/themes/theme-configuration.md | 56 ++++++ .../api/themes/theme-live-codeblock.md | 0 .../api/themes/theme-search-algolia.md | 0 .../docusaurus-asset-example-banner.png | Bin .../assets/docusaurus-asset-example.docx | Bin .../assets/docusaurus-asset-example.xyz | Bin .../blog.mdx | 0 .../browser-support.md | 0 .../cli.md | 2 +- .../configuration.md | 0 .../deployment.mdx | 4 +- .../docusaurus-core.md | 31 +-- .../guides/creating-pages.md | 8 +- .../guides/docs/docs-create-doc.mdx | 0 .../guides/docs/docs-introduction.md | 0 .../guides/docs/docs-multi-instance.mdx | 0 .../guides/docs/sidebar/autogenerated.md | 8 +- .../guides/docs/sidebar/index.md | 19 +- .../guides/docs/sidebar/items.md | 0 .../guides/docs/sidebar/multiple-sidebars.md | 2 + .../guides/docs/versioning.md | 2 +- .../_markdown-partial-example.mdx | 0 .../markdown-features-admonitions.mdx | 0 .../markdown-features-assets.mdx | 0 .../markdown-features-code-blocks.mdx | 184 ++++++++++++++++-- .../markdown-features-head-metadata.mdx | 34 +++- .../markdown-features-intro.mdx | 18 +- .../markdown-features-links.md | 52 +++++ .../markdown-features-math-equations.mdx | 0 .../markdown-features-plugins.mdx | 0 .../markdown-features-react.mdx | 6 +- .../markdown-features-react.module.css | 0 .../markdown-features-tabs-styles.module.css | 0 .../markdown-features-tabs.mdx | 0 .../markdown-features-toc.mdx} | 98 ++++++++-- .../guides/whats-next.md | 0 .../i18n/i18n-crowdin.mdx | 0 .../i18n/i18n-git.md | 0 .../i18n/i18n-introduction.md | 0 .../i18n/i18n-tutorial.md | 56 +++++- .../installation.md | 27 +-- .../introduction.md | 0 .../migration/migration-automated.md | 0 .../migration/migration-manual.md | 2 +- .../migration/migration-overview.md | 0 .../migration/migration-translated-sites.md | 0 .../migration/migration-versioned-sites.md | 0 .../playground.mdx | 0 .../search.md | 0 .../seo.md | 0 .../static-assets.md | 0 .../styling-layout.md | 0 .../swizzling.md | 0 .../typescript-support.md | 6 +- .../using-plugins.md | 176 +++++++++-------- ...on => version-2.0.0-beta.20-sidebars.json} | 5 +- website/versions.json | 5 +- website/versionsArchived.json | 1 + 96 files changed, 1153 insertions(+), 400 deletions(-) delete mode 100644 website/versioned_docs/version-2.0.0-beta.18/guides/docs/docs-markdown-features.mdx delete mode 100644 website/versioned_docs/version-2.0.0-beta.18/guides/markdown-features/markdown-features-headings.mdx rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/advanced/architecture.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/advanced/client.md (65%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/advanced/index.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/advanced/plugins.md (99%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/advanced/routing.md (98%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/advanced/ssg.md (93%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/docusaurus.config.js.md (75%) create mode 100644 website/versioned_docs/version-2.0.0-beta.20/api/misc/_category_.yml create mode 100644 website/versioned_docs/version-2.0.0-beta.20/api/misc/create-docusaurus.md create mode 100644 website/versioned_docs/version-2.0.0-beta.20/api/misc/eslint-plugin/README.md create mode 100644 website/versioned_docs/version-2.0.0-beta.20/api/misc/eslint-plugin/no-untranslated-text.md create mode 100644 website/versioned_docs/version-2.0.0-beta.20/api/misc/eslint-plugin/string-literal-i18n-messages.md create mode 100644 website/versioned_docs/version-2.0.0-beta.20/api/misc/img/logger-demo.png create mode 100644 website/versioned_docs/version-2.0.0-beta.20/api/misc/logger.md rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/plugin-methods/README.md (99%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/plugin-methods/_category_.yml (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/plugin-methods/extend-infrastructure.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/plugin-methods/i18n-lifecycles.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/plugin-methods/lifecycle-apis.md (98%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/plugin-methods/static-methods.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/plugins/_category_.yml (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/plugins/overview.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/plugins/plugin-client-redirects.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/plugins/plugin-content-blog.md (98%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/plugins/plugin-content-docs.md (78%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/plugins/plugin-content-pages.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/plugins/plugin-debug.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/plugins/plugin-google-analytics.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/plugins/plugin-google-gtag.md (98%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/plugins/plugin-ideal-image.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/plugins/plugin-pwa.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/plugins/plugin-sitemap.md (80%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/themes/_category_.yml (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/themes/overview.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/themes/theme-classic.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/themes/theme-configuration.md (94%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/themes/theme-live-codeblock.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/api/themes/theme-search-algolia.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/assets/docusaurus-asset-example-banner.png (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/assets/docusaurus-asset-example.docx (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/assets/docusaurus-asset-example.xyz (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/blog.mdx (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/browser-support.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/cli.md (99%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/configuration.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/deployment.mdx (99%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/docusaurus-core.md (98%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/guides/creating-pages.md (94%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/guides/docs/docs-create-doc.mdx (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/guides/docs/docs-introduction.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/guides/docs/docs-multi-instance.mdx (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/guides/docs/sidebar/autogenerated.md (95%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/guides/docs/sidebar/index.md (86%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/guides/docs/sidebar/items.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/guides/docs/sidebar/multiple-sidebars.md (94%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/guides/docs/versioning.md (98%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/guides/markdown-features/_markdown-partial-example.mdx (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/guides/markdown-features/markdown-features-admonitions.mdx (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/guides/markdown-features/markdown-features-assets.mdx (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/guides/markdown-features/markdown-features-code-blocks.mdx (73%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/guides/markdown-features/markdown-features-head-metadata.mdx (65%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/guides/markdown-features/markdown-features-intro.mdx (67%) create mode 100644 website/versioned_docs/version-2.0.0-beta.20/guides/markdown-features/markdown-features-links.md rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/guides/markdown-features/markdown-features-math-equations.mdx (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/guides/markdown-features/markdown-features-plugins.mdx (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/guides/markdown-features/markdown-features-react.mdx (97%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/guides/markdown-features/markdown-features-react.module.css (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/guides/markdown-features/markdown-features-tabs-styles.module.css (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/guides/markdown-features/markdown-features-tabs.mdx (100%) rename website/versioned_docs/{version-2.0.0-beta.18/guides/markdown-features/markdown-features-inline-toc.mdx => version-2.0.0-beta.20/guides/markdown-features/markdown-features-toc.mdx} (53%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/guides/whats-next.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/i18n/i18n-crowdin.mdx (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/i18n/i18n-git.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/i18n/i18n-introduction.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/i18n/i18n-tutorial.md (89%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/installation.md (88%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/introduction.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/migration/migration-automated.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/migration/migration-manual.md (99%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/migration/migration-overview.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/migration/migration-translated-sites.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/migration/migration-versioned-sites.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/playground.mdx (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/search.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/seo.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/static-assets.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/styling-layout.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/swizzling.md (100%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/typescript-support.md (98%) rename website/versioned_docs/{version-2.0.0-beta.18 => version-2.0.0-beta.20}/using-plugins.md (75%) rename website/versioned_sidebars/{version-2.0.0-beta.18-sidebars.json => version-2.0.0-beta.20-sidebars.json} (96%) diff --git a/CHANGELOG.md b/CHANGELOG.md index a7fae793e279..bb3245d49f70 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,32 @@ # Docusaurus 2 Changelog +## 2.0.0-beta.20 (2022-05-05) + +#### :bug: Bug Fix + +- `docusaurus` + - [#7342](https://github.com/facebook/docusaurus/pull/7342) fix: avoid flash of page scrolling to top on refresh ([@slorber](https://github.com/slorber)) + - [#7329](https://github.com/facebook/docusaurus/pull/7329) fix(core): inject docusaurus version into SSR as local ([@RDIL](https://github.com/RDIL)) +- `docusaurus-theme-classic` + - [#7341](https://github.com/facebook/docusaurus/pull/7341) fix(theme-classic): properly highlight code block line numbers ([@Josh-Cena](https://github.com/Josh-Cena)) + +#### :memo: Documentation + +- [#7334](https://github.com/facebook/docusaurus/pull/7334) feat(website): make canary release page display actual canary version name ([@Josh-Cena](https://github.com/Josh-Cena)) +- [#7343](https://github.com/facebook/docusaurus/pull/7343) docs: add page for create-docusaurus API documentation ([@Josh-Cena](https://github.com/Josh-Cena)) +- [#7340](https://github.com/facebook/docusaurus/pull/7340) docs: add Yandex Metrika plugin to community plugins ([@sgromkov](https://github.com/sgromkov)) +- [#7336](https://github.com/facebook/docusaurus/pull/7336) fix(website): fix multiple accessibility issues around color contrast ([@Josh-Cena](https://github.com/Josh-Cena)) +- [#7327](https://github.com/facebook/docusaurus/pull/7327) docs: add clarity to versioning behavior ([@pepopowitz](https://github.com/pepopowitz)) + +#### Committers: 6 + +- Alexey Pyltsyn ([@lex111](https://github.com/lex111)) +- Joshua Chen ([@Josh-Cena](https://github.com/Josh-Cena)) +- Reece Dunham ([@RDIL](https://github.com/RDIL)) +- Sergey Gromkov ([@sgromkov](https://github.com/sgromkov)) +- Steven Hicks ([@pepopowitz](https://github.com/pepopowitz)) +- Sébastien Lorber ([@slorber](https://github.com/slorber)) + ## 2.0.0-beta.19 (2022-05-04) #### :rocket: New Feature diff --git a/website/versioned_docs/version-2.0.0-beta.18/guides/docs/docs-markdown-features.mdx b/website/versioned_docs/version-2.0.0-beta.18/guides/docs/docs-markdown-features.mdx deleted file mode 100644 index 40be16cb9e54..000000000000 --- a/website/versioned_docs/version-2.0.0-beta.18/guides/docs/docs-markdown-features.mdx +++ /dev/null @@ -1,39 +0,0 @@ ---- -id: markdown-features -title: Docs Markdown Features -description: Docusaurus Markdown features that are specific to the docs plugin -slug: /docs-markdown-features ---- - -Docs can use any [Markdown feature](../markdown-features/markdown-features-intro.mdx) and have a few additional docs-specific Markdown features. - -## Markdown front matter {#markdown-front-matter} - -Markdown docs have their own [Markdown front matter API](../../api/plugins/plugin-content-docs.md#markdown-front-matter). - -## Referencing other documents {#referencing-other-documents} - -If you want to reference another document file, you could use the relative path of the document you want to link to. - -Docusaurus will convert the file path to be the final document url path (and remove the `.md` extension). - -For example, if you are in `folder/doc1.md` and you want to reference `folder/doc2.md`, `folder/subfolder/doc3.md` and `otherFolder/doc4.md`: - -```md -I am referencing a [document](doc2.md). - -Reference to another [document in a subfolder](subfolder/doc3.md). - -[Relative document](../otherFolder/doc4.md) referencing works as well. -``` - -:::tip - -Using relative _file_ paths (with `.md` extensions) instead of relative _URL_ links provides the following benefits: - -- links will keep working on the GitHub interface -- you can customize the document slugs without having to update all the links -- a versioned doc will link to another doc of the exact same version -- relative links are very likely to break if you update the [`trailingSlash` config](../../api/docusaurus.config.js.md#trailing-slash) - -::: diff --git a/website/versioned_docs/version-2.0.0-beta.18/guides/markdown-features/markdown-features-headings.mdx b/website/versioned_docs/version-2.0.0-beta.18/guides/markdown-features/markdown-features-headings.mdx deleted file mode 100644 index a4beb7bba3fe..000000000000 --- a/website/versioned_docs/version-2.0.0-beta.18/guides/markdown-features/markdown-features-headings.mdx +++ /dev/null @@ -1,57 +0,0 @@ ---- -id: headings -title: Headings -description: Using Markdown headings -slug: /markdown-features/headings ---- - -## Markdown headings {#markdown-headings} - -You can use regular Markdown headings. - -``` -## Level 2 title - -### Level 3 title - -#### Level 4 title -``` - -Markdown headings appear as a table of contents entry. - -## Heading ids {#heading-ids} - -Each heading has an id that can be automatically generated or explicitly specified. - -Heading ids allow you to link to a specific document heading in Markdown or JSX: - -```md -[link](#heading-id) -``` - -```jsx -link -``` - -### Generated ids {#generated-ids} - -By default, Docusaurus will generate heading ids for you, based on the heading text. For example, `### Hello World` will have id `hello-world`. - -Generated ids have **some limits**: - -- The id might not look good -- You might want to **change or translate** the text without updating the existing id - -### Explicit ids {#explicit-ids} - -A special Markdown syntax lets you set an **explicit heading id**: - -```md -### Hello World {#my-explicit-id} -``` - -:::tip - -Use the **[write-heading-ids](../../cli.md#docusaurus-write-heading-ids-sitedir)** CLI command to add explicit ids to all your Markdown documents. - -::: diff --git a/website/versioned_docs/version-2.0.0-beta.18/advanced/architecture.md b/website/versioned_docs/version-2.0.0-beta.20/advanced/architecture.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.18/advanced/architecture.md rename to website/versioned_docs/version-2.0.0-beta.20/advanced/architecture.md diff --git a/website/versioned_docs/version-2.0.0-beta.18/advanced/client.md b/website/versioned_docs/version-2.0.0-beta.20/advanced/client.md similarity index 65% rename from website/versioned_docs/version-2.0.0-beta.18/advanced/client.md rename to website/versioned_docs/version-2.0.0-beta.20/advanced/client.md index ef4c4d220c60..6019e7328997 100644 --- a/website/versioned_docs/version-2.0.0-beta.18/advanced/client.md +++ b/website/versioned_docs/version-2.0.0-beta.20/advanced/client.md @@ -86,7 +86,7 @@ Client modules are part of your site's bundle, just like theme components. Howev These modules are imported globally before React even renders the initial UI. -```js title="App.tsx" +```js title="@docusaurus/core/App.tsx" // How it works under the hood import '@generated/client-modules'; ``` @@ -117,5 +117,70 @@ CSS stylesheets imported as client modules are [global](../styling-layout.md#glo } ``` - - +### Client module lifecycles {#client-module-lifecycles} + +Besides introducing side-effects, client modules can optionally export two lifecycle functions: `onRouteUpdate` and `onRouteDidUpdate`. + +Because Docusaurus builds a single-page application, `script` tags will only be executed the first time the page loads, but will not re-execute on page transitions. These lifecycles are useful if you have some imperative JS logic that should execute every time a new page has loaded, e.g., to manipulate DOM elements, to send analytics data, etc. + +For every route transition, there will be several important timings: + +1. The user clicks a link, which causes the router to change its current location. +2. Docusaurus preloads the next route's assets, while keeping displaying the current page's content. +3. The next route's assets have loaded. +4. The new location's route component gets rendered to DOM. + +`onRouteUpdate` will be called at event (2), and `onRouteDidUpdate` will be called at (4). They both receive the current location and the previous location (which can be `null`, if this is the first screen). + +`onRouteUpdate` can optionally return a "cleanup" callback, which will be called at (3). For example, if you want to display a progress bar, you can start a timeout in `onRouteUpdate`, and clear the timeout in the callback. (The classic theme already provides an `nprogress` integration this way.) + +Note that the new page's DOM is only available during event (4). If you need to manipulate the new page's DOM, you'll likely want to use `onRouteDidUpdate`, which will be fired as soon as the DOM on the new page has mounted. + +```js title="myClientModule.js" +import type {Location} from 'history'; + +export function onRouteDidUpdate({location, previousLocation}) { + // Don't execute if we are still on the same page; the lifecycle may be fired + // because the hash changes (e.g. when navigating between headings) + if (location.pathname !== previousLocation?.pathname) { + const title = document.getElementsByTagName('h1')[0]; + if (title) { + title.innerText += '❤️'; + } + } +} + +export function onRouteUpdate({location, previousLocation}) { + if (location.pathname !== previousLocation?.pathname) { + const progressBarTimeout = window.setTimeout(() => { + nprogress.start(); + }, delay); + return () => window.clearTimeout(progressBarTimeout); + } + return undefined; +} +``` + +Or, if you are using TypeScript and you want to leverage contextual typing: + +```ts title="myClientModule.ts" +import type {ClientModule} from '@docusaurus/types'; + +const module: ClientModule = { + onRouteUpdate({location, previousLocation}) { + // ... + }, + onRouteDidUpdate({location, previousLocation}) { + // ... + }, +}; +export default module; +``` + +Both lifecycles will fire on first render, but they will not fire on server-side, so you can safely access browser globals in them. + +:::tip Prefer using React + +Client module lifecycles are purely imperative, and you can't use React hooks or access React contexts within them. If your operations are state-driven or involve complicated DOM manipulations, you should consider [swizzling components](../swizzling.md) instead. + +::: diff --git a/website/versioned_docs/version-2.0.0-beta.18/advanced/index.md b/website/versioned_docs/version-2.0.0-beta.20/advanced/index.md similarity index 100% rename from website/versioned_docs/version-2.0.0-beta.18/advanced/index.md rename to website/versioned_docs/version-2.0.0-beta.20/advanced/index.md diff --git a/website/versioned_docs/version-2.0.0-beta.18/advanced/plugins.md b/website/versioned_docs/version-2.0.0-beta.20/advanced/plugins.md similarity index 99% rename from website/versioned_docs/version-2.0.0-beta.18/advanced/plugins.md rename to website/versioned_docs/version-2.0.0-beta.20/advanced/plugins.md index 5e45b9d82bfa..29910ff0e2f9 100644 --- a/website/versioned_docs/version-2.0.0-beta.18/advanced/plugins.md +++ b/website/versioned_docs/version-2.0.0-beta.20/advanced/plugins.md @@ -51,7 +51,7 @@ module.exports = { Then in the folder `my-plugin`, you can create an `index.js` such as this: -```js title="my-plugin.js" +```js title="my-plugin/index.js" module.exports = async function myPlugin(context, options) { // ... return { diff --git a/website/versioned_docs/version-2.0.0-beta.18/advanced/routing.md b/website/versioned_docs/version-2.0.0-beta.20/advanced/routing.md similarity index 98% rename from website/versioned_docs/version-2.0.0-beta.18/advanced/routing.md rename to website/versioned_docs/version-2.0.0-beta.20/advanced/routing.md index 9aca36f249bb..82c85b7aae12 100644 --- a/website/versioned_docs/version-2.0.0-beta.18/advanced/routing.md +++ b/website/versioned_docs/version-2.0.0-beta.20/advanced/routing.md @@ -257,14 +257,14 @@ If you put some HTML pages under the `static` folder, they will be copied to the -- /pure-html +- [/pure-html](/pure-html) - [pathname:///pure-html](pathname:///pure-html) :::tip -The first link will trigger a "broken links detected" check during the production build. +The first link will **not** trigger a "broken links detected" check during the production build, because the respective file actually exists. Nevertheless, when you click on the link, a "page not found" will be displayed until you refresh. ::: diff --git a/website/versioned_docs/version-2.0.0-beta.18/advanced/ssg.md b/website/versioned_docs/version-2.0.0-beta.20/advanced/ssg.md similarity index 93% rename from website/versioned_docs/version-2.0.0-beta.18/advanced/ssg.md rename to website/versioned_docs/version-2.0.0-beta.20/advanced/ssg.md index b5b4e81f9f58..0a394f9179b4 100644 --- a/website/versioned_docs/version-2.0.0-beta.18/advanced/ssg.md +++ b/website/versioned_docs/version-2.0.0-beta.20/advanced/ssg.md @@ -100,6 +100,8 @@ These HTML files are the first to arrive at the user's browser screen when a URL In CSR-only apps, all DOM elements are generated on client side with React, and the HTML file only ever contains one root element for React to mount DOM to; in SSR, React is already facing a fully built HTML page, and it only needs to correlate the DOM elements with the virtual DOM in its model. This step is called "hydration". After React has hydrated the static markup, the app starts to work as any normal React app. +Note that Docusaurus is ultimately a single-page application, so static site generation is only an optimization (_progressive enhancement_, as it's called), but our functionality does not fully depend on those HTML files. This is contrary to site generators like [Jekyll](https://jekyllrb.com/) and [Docusaurus v1](https://v1.docusaurus.io/), where all files are statically transformed to markup, and interactiveness is added through external JavaScript linked with `