docs(v2): use explicit heading IDs (#4460)

website/docs/guides/creating-pages.md

@@ -10,7 +10,7 @@ The functionality of pages is powered by `@docusaurus/plugin-content-pages`.
 
 You can use React components, or Markdown.
 
-## Add a React page
+## Add a React page {#add-a-react-page}
 
 Create a file `/src/pages/helloReact.js`:
 
@@ -50,7 +50,7 @@ You can also create TypeScript pages with the `.tsx` extension (`helloReact.tsx`
 
 :::
 
-## Add a Markdown page
+## Add a Markdown page {#add-a-markdown-page}
 
 Create a file `/src/pages/helloMarkdown.md`:
 
@@ -78,7 +78,7 @@ You can use the full power of React in Markdown pages too, refer to the [MDX](ht
 
 :::
 
-## Routing
+## Routing {#routing}
 
 If you are familiar with other static site generators like Jekyll and Next, this routing approach will feel familiar to you. Any JavaScript file you create under `/src/pages/` directory will be automatically converted to a website page, following the `/src/pages/` directory hierarchy. For example:
 
@@ -113,10 +113,10 @@ All JavaScript/TypeScript files within the `src/pages/` directory will have corr
 
 :::
 
-## Using React
+## Using React {#using-react}
 
 React is used as the UI library to create pages. Every page component should export a React component, and you can leverage on the expressiveness of React to build rich and interactive content.
 
-## Duplicate Routes
+## Duplicate Routes {#duplicate-routes}
 
 You may accidentally create multiple pages that are meant to be accessed on the same route. When this happens, Docusaurus will warn you about duplicate routes when you run `yarn start` or `yarn build`, but the site will still be built successfully. The page that was created last will be accessible, but it will override other conflicting pages. To resolve this issue, you should modify or remove any conflicting routes.

website/docs/guides/docs/docs-introduction.md

@@ -7,7 +7,7 @@ slug: /docs-introduction
 
 The docs feature provides users with a way to organize Markdown files in a hierarchical format.
 
-## Document ID
+## Document ID {#document-id}
 
 Every document has a unique `id`. By default, a document `id` is the name of the document (without the extension) relative to the root docs directory.
 
@@ -49,7 +49,7 @@ It is possible to use:
 
 :::
 
-## Home page docs
+## Home page docs {#home-page-docs}
 
 If you want a document to be available at the root, and have a path like `https://v2.docusaurus.io/docs/`, you can use the slug frontmatter:
 
@@ -61,7 +61,7 @@ slug: /
 Lorem ipsum
 ```
 
-## Docs-only mode
+## Docs-only mode {#docs-only-mode}
 
 If you only want the documentation feature, you can run your Docusaurus 2 site without a landing page and display your documentation page as the index page instead.
 

website/docs/guides/docs/docs-markdown-features.mdx

@@ -7,11 +7,11 @@ 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 frontmatter
+## Markdown frontmatter {#markdown-frontmatter}
 
 Markdown docs have their own [Markdown frontmatter](../../api/plugins/plugin-content-docs.md#markdown-frontmatter)
 
-## Referencing other documents
+## Referencing other documents {#referencing-other-documents}
 
 If you want to reference another document file, you could use the name of the document you want to reference. Docusaurus will convert the file path to be the final website path (and remove the `.md`).
 

website/docs/guides/docs/docs-multi-instance.mdx

@@ -13,13 +13,13 @@ This feature is only useful for [versioned documentations](./versioning.md). It
 
 :::
 
-## Use-cases
+## Use-cases {#use-cases}
 
 Sometimes you want a Docusaurus site to host 2 distinct sets of documentation (or more).
 
 These documentations may even have different versioning/release lifecycles.
 
-### Mobile SDKs documentation
+### Mobile SDKs documentation {#mobile-sdks-documentation}
 
 If you build a cross-platform mobile SDK, you may have 2 documentations:
 
@@ -36,7 +36,7 @@ If someone edits the iOS documentation, is it really useful to rebuild everythin
 
 :::
 
-### Versioned and unversioned doc
+### Versioned and unversioned doc {#versioned-and-unversioned-doc}
 
 Sometimes, you want some documents to be versioned, while other documents are more "global", and it feels useless to version them.
 
@@ -45,7 +45,7 @@ We use this pattern on the Docusaurus website itself:
 - The [/docs/\*](/docs) section is versioned
 - The [/community/\*](/community/support) section is unversioned
 
-## Setup
+## Setup {#setup}
 
 Let's consider we 2 documentations:
 
@@ -138,7 +138,7 @@ We consider that the `product` instance is the most important one, and make it t
 
 :::
 
-## Versioned paths
+## Versioned paths {#versioned-paths}
 
 Each instance will store versioned docs in a distinct folder.
 
@@ -162,7 +162,7 @@ The instance paths will be simpler, and retro-compatible with a single-instance
 
 :::
 
-## Tagging new versions
+## Tagging new versions {#tagging-new-versions}
 
 Each plugin instance will have its own cli command to tag a new version. They will be displayed if you run:
 
@@ -182,7 +182,7 @@ To version the non-default/community docs plugin instance:
 npm run docusaurus docs:version:community 1.0.0
 ```
 
-## Docs navbar items
+## Docs navbar items {#docs-navbar-items}
 
 Each docs-related [theme navbar items](../../api/themes/theme-configuration.md#navbar) take an optional `docsPluginId` attribute.
 

website/docs/guides/docs/sidebar.md

@@ -27,7 +27,7 @@ module.exports = {
 };
 ```
 
-## Sidebar object
+## Sidebar object {#sidebar-object}
 
 A sidebar object contains [sidebar items](#understanding-sidebar-items) and it is defined like this:
 
@@ -83,7 +83,7 @@ Shorthand notation relies on the iteration order of JavaScript object keys for t
 
 :::
 
-## Using multiple sidebars
+## Using multiple sidebars {#using-multiple-sidebars}
 
 You can have multiple sidebars for different Markdown files by adding more top-level keys to the exported object.
 
@@ -107,7 +107,7 @@ For example, with the above example, when displaying the `doc2` page, the sideba
 
 For more information about sidebars and how they relate to doc pages, see [Navbar doc link](../../api/themes/theme-configuration.md#navbar-doc-link).
 
-## Understanding sidebar items
+## Understanding sidebar items {#understanding-sidebar-items}
 
 As the name implies, `SidebarItem` is an item defined in a Sidebar. A SidebarItem as a `type` that defines what the item links to.
 
@@ -118,7 +118,7 @@ As the name implies, `SidebarItem` is an item defined in a Sidebar. A SidebarIte
 - [Ref](#creating-a-link-to-page-without-sidebar)
 - [Category](#creating-a-hierarchy)
 
-### Linking to a doc page
+### Linking to a doc page {#linking-to-a-doc-page}
 
 Set `type` to `doc` to link to a documentation page. This is the default type.
 
@@ -163,7 +163,7 @@ module.exports = {
 };
 ```
 
-### Creating a generic link
+### Creating a generic link {#creating-a-generic-link}
 
 Set `type` to `link` to link to a non-documentation page. For example, to create an external link.
 
@@ -185,7 +185,7 @@ Example:
 }
 ```
 
-### Creating a link to page without sidebar
+### Creating a link to page without sidebar {#creating-a-link-to-page-without-sidebar}
 
 Set `type` to `ref` to link to a documentation page without binding it to a sidebar. This means the sidebar disappears when the user displays the linked page.
 
@@ -205,7 +205,7 @@ Example:
 }
 ```
 
-### Creating a hierarchy
+### Creating a hierarchy {#creating-a-hierarchy}
 
 The Sidebar item type that creates a hierarchy in the sidebar. Set `type` to `category`.
 
@@ -260,7 +260,7 @@ module.exports = {
 };
 ```
 
-#### Collapsible categories
+#### Collapsible categories {#collapsible-categories}
 
 For sites with a sizable amount of content, we support the option to expand/collapse a category to toggle the display of its contents. Categories are collapsible by default. If you want them to be always expanded, set `themeConfig.sidebarCollapsible` to `false`:
 
@@ -274,7 +274,7 @@ module.exports = {
 };
 ```
 
-#### Expanded categories by default
+#### Expanded categories by default {#expanded-categories-by-default}
 
 For docs that have collapsible categories, you may want more fine-grain control over certain categories. If you want specific categories to be always expanded, you can set `collapsed` to `false`:
 
@@ -294,7 +294,7 @@ module.exports = {
 };
 ```
 
-## Hideable sidebar
+## Hideable sidebar {#hideable-sidebar}
 
 Using the enabled `themeConfig.hideableSidebar` option, you can make the entire sidebar hidden, allowing you to better focus your users on the content. This is especially useful when content consumption on medium screens (e.g. on tablets).
 
@@ -308,7 +308,7 @@ module.exports = {
 };
 ```
 
-## Passing custom props
+## Passing custom props {#passing-custom-props}
 
 To pass in custom props to a swizzled sidebar item, add the optional `customProps` object to any of the items:
 

website/docs/guides/docs/versioning.md

@@ -16,7 +16,7 @@ Most of the time, you don't need versioning as it will just increase your build
 
 To better understand how versioning works and see if it suits your needs, you can read on below.
 
-## Directory structure
+## Directory structure {#directory-structure}
 
 ```shell
 website
@@ -50,7 +50,7 @@ The table below explains how a versioned file maps to its version and the genera
 | `versioned_docs/version-1.1.0/hello.md` | 1.1.0 (latest) | /docs/hello       |
 | `docs/hello.md`                         | next           | /docs/next/hello  |
 
-### Tagging a new version
+### Tagging a new version {#tagging-a-new-version}
 
 1. First, make sure your content in the `docs` directory is ready to be frozen as a version. A version always should be based from master.
 1. Enter a new version number.
@@ -65,9 +65,9 @@ When tagging a new version, the document versioning mechanism will:
 - Create a versioned sidebars file based from your current [sidebar](docs-introduction.md#sidebar) configuration (if it exists) - saved as `versioned_sidebars/version-<version>-sidebars.json`.
 - Append the new version number to `versions.json`.
 
-## Docs
+## Docs {#docs}
 
-### Creating new docs
+### Creating new docs {#creating-new-docs}
 
 1. Place the new file into the corresponding version folder.
 1. Include the reference for the new file into the corresponding sidebar file, according to version number.
@@ -92,7 +92,7 @@ versioned_docs/version-1.0.0/new.md
 versioned_sidebars/version-1.0.0-sidebars.json
 ```
 
-### Linking docs
+### Linking docs {#linking-docs}
 
 - Remember to include the `.md` extension.
 - Files will be linked to correct corresponding version.
@@ -104,11 +104,11 @@ The [@hello](hello.md#paginate) document is great!
 See the [Tutorial](../getting-started/tutorial.md) for more info.
 ```
 
-## Versions
+## Versions {#versions}
 
 Each directory in `versioned_docs/` will represent a documentation version.
 
-### Updating an existing version
+### Updating an existing version {#updating-an-existing-version}
 
 You can update multiple docs versions at the same time because each directory in `versioned_docs/` represents specific routes when published.
 
@@ -118,7 +118,7 @@ You can update multiple docs versions at the same time because each directory in
 
 Example: When you change any file in `versioned_docs/version-2.6/`, it will only affect the docs for version `2.6`.
 
-### Deleting an existing version
+### Deleting an existing version {#deleting-an-existing-version}
 
 You can delete/remove versions as well.
 
@@ -137,9 +137,9 @@ Example:
 2. Delete the versioned docs directory. Example: `versioned_docs/version-1.8.0`.
 3. Delete the versioned sidebars file. Example: `versioned_sidebars/version-1.8.0-sidebars.json`.
 
-## Recommended practices
+## Recommended practices {#recommended-practices}
 
-### Figure out the behavior for the "current" version
+### Figure out the behavior for the "current" version {#figure-out-the-behavior-for-the-current-version}
 
 The "current" version is the version name for the `./docs` folder.
 
@@ -168,17 +168,17 @@ The docs in `./docs` will be served at `/docs/1.0.0` instead of `/docs/next`, an
 
 See [docs plugin configuration](../../api/plugins/plugin-content-docs.md) for more details.
 
-### Version your documentation only when needed
+### Version your documentation only when needed {#version-your-documentation-only-when-needed}
 
 For example, you are building a documentation for your npm package `foo` and you are currently in version 1.0.0. You then release a patch version for a minor bug fix and it's now 1.0.1.
 
 Should you cut a new documentation version 1.0.1? **You probably shouldn't**. 1.0.1 and 1.0.0 docs shouldn't differ according to semver because there are no new features!. Cutting a new version for it will only just create unnecessary duplicated files.
 
-### Keep the number of versions small
+### Keep the number of versions small {#keep-the-number-of-versions-small}
 
 As a good rule of thumb, try to keep the number of your versions below 10. **It is very likely** that you will have a lot of obsolete versioned documentation that nobody even reads anymore. For example, [Jest](https://jestjs.io/versions) is currently in version `24.9`, and only maintains several latest documentation version with the lowest being `22.X`. Keep it small 😊
 
-### Use absolute import within the docs
+### Use absolute import within the docs {#use-absolute-import-within-the-docs}
 
 Don't use relative paths import within the docs. Because when we cut a version the paths no longer work (the nesting level is different, among other reasons). You can utilize the `@site` alias provided by docusaurus, that points to the `website` directory. Example:
 
@@ -187,7 +187,7 @@ Don't use relative paths import within the docs. Because when we cut a version t
 + import Foo from '@site/src/components/Foo';
 ```
 
-### Global or versioned colocated assets
+### Global or versioned colocated assets {#global-or-versioned-colocated-assets}
 
 You should decide if assets like images and files are per version or shared between versions
 

website/docs/guides/markdown-features/markdown-features-admonitions.mdx

@@ -69,7 +69,7 @@ Danger danger, mayday!
 
 :::
 
-## Specifying title
+## Specifying title {#specifying-title}
 
 You may also specify an optional title
 

website/docs/guides/markdown-features/markdown-features-assets.mdx

@@ -20,7 +20,7 @@ Let's imagine the following file structure:
 /website/docs/assets/docusaurus-asset-example-pdf.pdf
 ```
 
-## Images
+## Images {#images}
 
 You can use images in Markdown, or by requiring them and using a JSX image tag:
 
@@ -57,7 +57,7 @@ If you are using [@docusaurus/plugin-ideal-image](../../using-plugins.md#docusau
 
 :::
 
-## Files
+## Files {#files}
 
 In the same way, you can link to existing assets by requiring them and using the returned url in videos, links etc.
 
@@ -83,7 +83,7 @@ or
 
 [Download this PDF using Markdown](../../assets/docusaurus-asset-example-pdf.pdf)
 
-## Inline SVGs
+## Inline SVGs {#inline-svgs}
 
 Docusaurus supports inlining SVGs out of the box.
 
@@ -117,7 +117,7 @@ html[data-theme='dark'] .themedDocusaurus [fill='#FFFF50'] {
 
 <DocusaurusSvg className="themedDocusaurus" />
 
-## Themed Images
+## Themed Images {#themed-images}
 
 Docusaurus supports themed images: the `ThemedImage` component (included in the classic/bootstrap themes) allows you to switch the image source based on the current theme.
 

website/docs/guides/markdown-features/markdown-features-code-blocks.mdx

@@ -7,7 +7,7 @@ slug: /markdown-features/code-blocks
 
 Code blocks within documentation are super-powered 💪.
 
-## Code title
+## Code title {#code-title}
 
 You can add a title to the code block by adding `title` key after the language (leave a space between them).
 
@@ -23,7 +23,7 @@ function HelloCodeTitle(props) {
 }
 ```
 
-## Syntax highlighting
+## Syntax highlighting {#syntax-highlighting}
 
 Code blocks are text blocks wrapped around by strings of 3 backticks. You may check out [this reference](https://github.com/mdx-js/specification) for specifications of MDX.
 
@@ -95,7 +95,7 @@ const prismIncludeLanguages = (Prism) => {
 
 You can refer to [Prism's official language definitions](https://github.com/PrismJS/prism/tree/master/components) when you are writing your own language definitions.
 
-## Line highlighting
+## Line highlighting {#line-highlighting}
 
 You can bring emphasis to certain lines of code by specifying line ranges after the language meta string (leave a space after the language).
 
@@ -220,7 +220,7 @@ Supported commenting syntax:
 
 If there's a syntax that is not currently supported, we are open to adding them! Pull requests welcome.
 
-## Interactive code editor
+## Interactive code editor {#interactive-code-editor}
 
 (Powered by [React Live](https://github.com/FormidableLabs/react-live))
 
@@ -292,7 +292,7 @@ function Clock(props) {
 }
 ```
 
-### Imports
+### Imports {#imports}
 
 :::caution react-live and imports
 
@@ -345,7 +345,7 @@ function MyPlayground(props) {
 }
 ```
 
-## Multi-language support code blocks
+## Multi-language support code blocks {#multi-language-support-code-blocks}
 
 With MDX, you can easily create interactive components within your documentation, for example, to display code in multiple programming languages and switching between them using a tabs component.
 

website/docs/guides/markdown-features/markdown-features-headings.mdx

@@ -5,7 +5,7 @@ description: Using Markdown headings
 slug: /markdown-features/headings
 ---
 
-## Markdown headings
+## Markdown headings {#markdown-headings}
 
 You can use regular Markdown headings.
 
@@ -19,7 +19,7 @@ You can use regular Markdown headings.
 
 Markdown headings appear as a table-of-contents entry.
 
-## Heading ids
+## Heading ids {#heading-ids}
 
 Each heading has an id that can be automatically generated, or explicitly specified.
 
@@ -33,7 +33,7 @@ Heading ids allow you to link to a specific document heading in Markdown or JSX:
 <Link to="#heading-id">link</Link>
 ```
 
-### Generated ids
+### Generated ids {#generated-ids}
 
 By default, Docusaurus will generate heading ids for you, based on the heading text.
 
@@ -44,7 +44,7 @@ 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 {#explicit-ids}
 
 A special Markdown syntax lets you set an **explicit heading id**:
 

website/docs/guides/markdown-features/markdown-features-inline-toc.mdx

@@ -11,7 +11,7 @@ Each markdown document displays a tab of content on the top-right corner.
 
 But it is also possible to display an inline table of contents directly inside a markdown document, thanks to MDX.
 
-## Full table of contents
+## Full table of contents {#full-table-of-contents}
 
 The `toc` variable is available in any MDX document, and contain all the top level headings of a MDX document.
 
@@ -31,7 +31,7 @@ import TOCInline from '@theme/TOCInline';
 </BrowserWindow>
 ```
 
-## Custom table of contents
+## Custom table of contents {#custom-table-of-contents}
 
 The `toc` props is just a list of table of contents items:
 
@@ -72,50 +72,50 @@ The underlying content is just an example to have more table-of-contents items a
 
 :::
 
-## Example Section 1
+## Example Section 1 {#example-section-1}
 
 Lorem ipsum
 
-### Example Subsection 1 a
+### Example Subsection 1 a {#example-subsection-1-a}
 
 Lorem ipsum
 
-### Example Subsection 1 b
+### Example Subsection 1 b {#example-subsection-1-b}
 
 Lorem ipsum
 
-### Example Subsection 1 c
+### Example Subsection 1 c {#example-subsection-1-c}
 
 Lorem ipsum
 
-## Example Section 2
+## Example Section 2 {#example-section-2}
 
 Lorem ipsum
 
-### Example Subsection 2 a
+### Example Subsection 2 a {#example-subsection-2-a}
 
 Lorem ipsum
 
-### Example Subsection 2 b
+### Example Subsection 2 b {#example-subsection-2-b}
 
 Lorem ipsum
 
-### Example Subsection 2 c
+### Example Subsection 2 c {#example-subsection-2-c}
 
 Lorem ipsum
 
-## Example Section 3
+## Example Section 3 {#example-section-3}
 
 Lorem ipsum
 
-### Example Subsection 3 a
+### Example Subsection 3 a {#example-subsection-3-a}
 
 Lorem ipsum
 
-### Example Subsection 3 b
+### Example Subsection 3 b {#example-subsection-3-b}
 
 Lorem ipsum
 
-### Example Subsection 3 c
+### Example Subsection 3 c {#example-subsection-3-c}
 
 Lorem ipsum

website/docs/guides/markdown-features/markdown-features-plugins.mdx

@@ -9,7 +9,7 @@ You can expand the MDX functionalities, using plugins.
 
 Docusaurus content plugins support both [Remark](https://github.com/remarkjs/remark) and [Rehype](https://github.com/rehypejs/rehype) plugins that work with MDX.
 
-## Configuring plugins
+## Configuring plugins {#configuring-plugins}
 
 An MDX plugin is usually a npm package, so you install them like other npm packages using npm.
 
@@ -50,7 +50,7 @@ module.exports = {
 };
 ```
 
-## Configuring plugin options
+## Configuring plugin options {#configuring-plugin-options}
 
 Some plugins can be configured and accept their own options. In that case, use the `[plugin, pluginOptions]` syntax, like so:
 

website/docs/guides/markdown-features/markdown-features-tabs.mdx

@@ -50,7 +50,7 @@ By default, tabs are rendered eagerly, but it is possible to load them lazily by
 
 :::
 
-## Syncing tab choices
+## Syncing tab choices {#syncing-tab-choices}
 
 You may want choices of the same kind of tabs to sync with each other. For example, you might want to provide different instructions for users on Windows vs users on macOS, and you want to changing all OS-specific instructions tabs in one click. To achieve that, you can give all related tabs the same `groupId` prop. Note that doing this will persist the choice in `localStorage` and all `<Tab>` instances with the same `groupId` will update automatically when the value of one of them is changed. Note that `groupID` are globally-namespaced.
 
@@ -190,7 +190,7 @@ Tab choices with different `groupId`s will not interfere with each other:
 </Tabs>
 ```
 
-## Customizing tabs
+## Customizing tabs {#customizing-tabs}
 
 You might want to customize the appearance of certain set of tabs. To do that you can pass the string in `className` prop and the specified CSS class will be added to the `Tabs` component: