facebook · Josh-Cena · Apr 30, 2022 · Apr 30, 2022 · Apr 30, 2022 · Apr 30, 2022
@@ -311,6 +311,7 @@ typedoc
 typesense
 unflat
 unist
+unlinkable
 unlocalized
 unmatch
 unnormalized

@@ -171,7 +171,7 @@ By default, the files are written in `website/i18n/<defaultLocale>/...`.
 
 ### `docusaurus write-heading-ids [siteDir] [files]` {#docusaurus-write-heading-ids-sitedir}
 
-Add [explicit heading ids](./guides/markdown-features/markdown-features-headings.mdx#explicit-ids) to the Markdown documents of your site.
+Add [explicit heading ids](./guides/markdown-features/markdown-features-toc.mdx#explicit-ids) to the Markdown documents of your site.
 
 | Name | Default | Description |
 | --- | --- | --- |

@@ -307,7 +307,9 @@ function isCategoryIndex({fileName, directories}) {
 
 For handwritten sidebar definitions, you would provide metadata to sidebar items through `sidebars.js`; for autogenerated, Docusaurus would read them from the item's respective file. In addition, you may want to adjust the relative position of each item because, by default, items within a sidebar slice will be generated in **alphabetical order** (using file and folder names).
 
-**For docs**: use additional front matter. The `label`, `className`, and `customProps` attributes are declared in front matter as `sidebar_label`, `sidebar_class_name`, and `sidebar_custom_props`, respectively. Position can be specified in the same way, via `sidebar_position` front matter.
+### Doc item metadata {#doc-item-metadata}
+
+The `label`, `className`, and `customProps` attributes are declared in front matter as `sidebar_label`, `sidebar_class_name`, and `sidebar_custom_props`, respectively. Position can be specified in the same way, via `sidebar_position` front matter.
 
 ```md title="docs/tutorials/tutorial-easy.md"
 ---
@@ -323,7 +325,9 @@ sidebar_class_name: green
 This is the easy tutorial!
 ```
 
-**For categories**: add a `_category_.json` or `_category_.yml` file in the respective folder. You can specify any category metadata and also the `position` metadata. `label`, `className`, `position`, and `customProps` will default to the respective values of the category's linked doc, if there is one.
+### Category item metadata {#category-item-metadata}
+
+Add a `_category_.json` or `_category_.yml` file in the respective folder. You can specify any category metadata and also the `position` metadata. `label`, `className`, `position`, and `customProps` will default to the respective values of the category's linked doc, if there is one.
 
 <Tabs>
 <TabItem value="JSON">

@@ -5,7 +5,9 @@ description: Declaring page-specific head metadata through MDX
 slug: /markdown-features/head-metadata
 ---
 
-# Head Metadata
+# Head metadata
+
+## Customizing head metadata {#customizing-head-metadata}
 
 Docusaurus automatically sets useful page metadata in `<html>`, `<head>` and `<body>` for you. It is possible to add extra metadata (or override existing ones) with the `<head>` tag in Markdown files:
 
@@ -42,10 +44,12 @@ My text
 </head>
 ```
 
-:::tip
-
 This `<head>` declaration has been added to the current Markdown doc as a demo. Open your browser DevTools and check how this page's metadata has been affected.
 
+:::note
+
+This feature is built on top of the Docusaurus [`<Head>`](./../../docusaurus-core.md#head) component. Refer to [react-helmet](https://github.com/nfl/react-helmet) for exhaustive documentation.
+
 :::
 
 :::tip You don't need this for regular SEO
@@ -54,8 +58,26 @@ Content plugins (e.g. docs and blog) provide front matter options like `descript
 
 :::
 
-:::note
+## Markdown page description {#markdown-page-description}
 
-This feature is built on top of the Docusaurus [`<Head>`](./../../docusaurus-core.md#head) component. Refer to [react-helmet](https://github.com/nfl/react-helmet) for exhaustive documentation.
+The Markdown pages' description metadata may be used in more places than the head metadata. For example, the docs plugin's [generated category index](../docs/sidebar/items.md#generated-index-page) uses the description metadata for the doc cards.
 
-:::
+By default, the description is the first content-ful line, with some efforts to convert it to plain text. For example, the following file...
+
+```md
+# Title
+
+Main content... May contain some [links](./file.md) or **emphasis**.
+```
+
+...will have the default description "Main content... May contain some links or emphasis". However, **it's not designed to be fully functional**. Where it fails to produce reasonable descriptions, you can explicitly provide one through front matter:
+
+```md
+---
+description: This description will override the default.
+---
+
+# Title
+
+Main content... May contain some [links](./file.md) or **emphasis**.
+```
@@ -426,7 +426,7 @@ The table of contents does not currently contain the imported Markdown headings.
 Within the MDX page, the following variables are available as globals:
 
 - `frontMatter`: the front matter as a record of string keys and values;
-- `toc`: the table of contents, as a tree of headings. See also [Inline TOC](./markdown-features-inline-toc.mdx) for a more concrete use-case.
+- `toc`: the table of contents, as a tree of headings. See also [Inline TOC](./markdown-features-toc.mdx#inline-table-of-contents) for a more concrete use-case.
 - `contentTitle`: the Markdown title, which is the first `h1` heading in the Markdown text. It's `undefined` if there isn't one (e.g. title specified in the front matter).
 
 ```jsx

@@ -1,15 +1,67 @@
 ---
-id: inline-toc
-title: Inline TOC
-description: Using inline table-of-contents inside Docusaurus Markdown
-slug: /markdown-features/inline-toc
+id: toc
+description: Customizing headings and table-of-contents in Markdown
+slug: /markdown-features/toc
 ---
 
 import BrowserWindow from '@site/src/components/BrowserWindow';
 
-Each Markdown document displays a table of contents 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.
+# Headings and Table of contents
+
+## Markdown headings {#markdown-headings}
+
+You can use regular Markdown headings.
+
+```md
+## Level 2 title
+
+### Level 3 title
+
+#### Level 4 title
+```
+
+Each Markdown heading will 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 to="#heading-id">link</Link>
+```
+
+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 limitations**:
+
+- The ID might not look good
+- You might want to **change or translate** the text without updating the existing ID
+
+A special Markdown syntax lets you set an **explicit heading id**:
+
+```md
+### Hello World {#my-explicit-id}
+```
 
-## Full table of contents {#full-table-of-contents}
+:::tip
+
+Use the **[write-heading-ids](../../cli.md#docusaurus-write-heading-ids-sitedir)** CLI command to add explicit ids to all your Markdown documents.
+
+:::
+
+:::caution Avoid colliding IDs
+
+Generated heading IDs will be guaranteed to be unique on each page, but if you use custom IDs, make sure each one appears exactly once on each page, or there will be two DOM elements with the same ID, which is invalid HTML semantics, and will lead to one heading being unlinkable.
+
+:::
+
+## Inline table of contents {#inline-table-of-contents}
+
+Each Markdown document displays a table of contents 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.
 
 The `toc` variable is available in any MDX document and contains all the headings of an MDX document. By default, only `h2` and `h3` headings are displayed in the TOC. You can change which heading levels are visible by setting `minHeadingLevel` or `maxHeadingLevel` for individual `TOCInline` components.
 
@@ -28,16 +80,14 @@ import TOCInline from '@theme/TOCInline';
 </BrowserWindow>
 ```
 
-## Custom table of contents {#custom-table-of-contents}
-
-The `toc` prop is just a list of heading items:
+The `toc` global is just a list of heading items:
 
 ```ts
-type TOCItem = {
+declare const toc: Array<{
   value: string;
   id: string;
   level: number;
-};
+}>;
 ```
 
 Note that the `toc` global is a flat array, so you can easily cut out unwanted nodes or insert extra nodes, and create a new TOC tree.
@@ -65,6 +115,26 @@ import TOCInline from '@theme/TOCInline';
 </BrowserWindow>
 ```
 
+## Customizing table of contents generation {#customizing-table-of-contents-generation}
+
+The table-of-contents is generated by parsing the Markdown source with a [Remark plugin](./markdown-features-plugins.mdx). There are known edge-cases where it generates false-positives and false-negatives.
+
+Markdown headings within hideable areas will still show up in the TOC. For example, headings within [`Tabs`](./markdown-features-tabs.mdx) and [`details`](./markdown-features-intro.mdx#details) will not be excluded.
+
+Non-markdown headings will not show up in the TOC. This can be used to your advantage to tackle the aforementioned issue.
+
+```md
+<details>
+<summary>Some details containing headings</summary>
+<h2 id="#heading-id">I'm a heading that will not show up in the TOC</h2>
+
+Some content...
+
+</details>
+```
+
+The ability to ergonomically insert extra headings or ignore certain headings is a work-in-progress. If this feature is important to you, please report your use-case in [this issue](https://github.com/facebook/docusaurus/issues/6201).
+
 ---
 
 :::caution

@@ -423,7 +423,7 @@ Generated ids are not always a good fit for localized sites, as it requires you
 + [link](#bonjour-le-monde)
 ```
 
-For localized sites, it is recommended to use **[explicit heading ids](../guides/markdown-features/markdown-features-headings.mdx#explicit-ids)**.
+For localized sites, it is recommended to use **[explicit heading ids](../guides/markdown-features/markdown-features-toc.mdx#explicit-ids)**.
 
 :::
 

@@ -573,7 +573,7 @@ The following code could be helpful for migration of various pages:
 
 ### Replace AUTOGENERATED_TABLE_OF_CONTENTS {#replace-autogenerated_table_of_contents}
 
-This feature is replaced by [inline table of content](../guides/markdown-features/markdown-features-inline-toc.mdx)
+This feature is replaced by [inline table of content](../guides/markdown-features/markdown-features-toc.mdx#inline-table-of-contents)
 
 ### Update Markdown syntax to be MDX-compatible {#update-markdown-syntax-to-be-mdx-compatible}
 

@@ -77,8 +77,7 @@ const sidebars = {
             'guides/markdown-features/tabs',
             'guides/markdown-features/code-blocks',
             'guides/markdown-features/admonitions',
-            'guides/markdown-features/headings',
-            'guides/markdown-features/inline-toc',
+            'guides/markdown-features/toc',
             'guides/markdown-features/assets',
             'guides/markdown-features/links',
             'guides/markdown-features/plugins',

@@ -6,8 +6,14 @@
 /docs/next/docusaurus.config.js                  /docs/next/api/docusaurus-config
 /docs/lifecycle-apis                             /docs/api/plugin-methods/
 /docs/next/lifecycle-apis                        /docs/next/api/plugin-methods/
-/docs/using-themes                               /docs/advanced/swizzling
-/docs/next/using-themes                          /docs/next/advanced/swizzling
+/docs/using-themes                               /docs/swizzling
+/docs/next/using-themes                          /docs/next/swizzling
+/docs/advanced/swizzling                         /docs/swizzling
+/docs/next/advanced/swizzling                    /docs/next/swizzling
+/docs/markdown-features/inline-toc               /docs/markdown-features/toc
+/docs/next/markdown-features/inline-toc          /docs/next/markdown-features/toc
+/docs/markdown-features/headings                 /docs/markdown-features/toc
+/docs/next/markdown-features/headings            /docs/next/markdown-features/toc
 
 
 # v2.docusaurus.io domain redirect after we put v2 on docusaurus.io
-Original file line number
+Diff line change
@@ Expand Up @@
     + [link](#bonjour-le-monde)
     ```
-    For localized sites, it is recommended to use **[explicit heading ids](../guides/markdown-features/markdown-features-headings.mdx#explicit-ids)**.
+    For localized sites, it is recommended to use **[explicit heading ids](../guides/markdown-features/markdown-features-toc.mdx#explicit-ids)**.
     :::
@@ Expand Down @@