From df0224ac646674b15fdffd1db6752f069415e081 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Sat, 30 Apr 2022 20:52:46 +0800 Subject: [PATCH 1/3] docs: multiple documentation improvements --- project-words.txt | 1 + .../docs/guides/docs/sidebar/autogenerated.md | 8 +- .../markdown-features-head-metadata.mdx | 34 +++++-- .../markdown-features-headings.mdx | 57 ------------ ...line-toc.mdx => markdown-features-toc.mdx} | 92 ++++++++++++++++--- website/sidebars.js | 3 +- website/static/_redirects | 10 +- 7 files changed, 125 insertions(+), 80 deletions(-) delete mode 100644 website/docs/guides/markdown-features/markdown-features-headings.mdx rename website/docs/guides/markdown-features/{markdown-features-inline-toc.mdx => markdown-features-toc.mdx} (55%) diff --git a/project-words.txt b/project-words.txt index 4bf268862fcd..73e68d7b8edd 100644 --- a/project-words.txt +++ b/project-words.txt @@ -311,6 +311,7 @@ typedoc typesense unflat unist +unlinkable unlocalized unmatch unnormalized diff --git a/website/docs/guides/docs/sidebar/autogenerated.md b/website/docs/guides/docs/sidebar/autogenerated.md index 239888b99f30..a8268f45813c 100644 --- a/website/docs/guides/docs/sidebar/autogenerated.md +++ b/website/docs/guides/docs/sidebar/autogenerated.md @@ -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. diff --git a/website/docs/guides/markdown-features/markdown-features-head-metadata.mdx b/website/docs/guides/markdown-features/markdown-features-head-metadata.mdx index 1a2c04095c1c..66fd5748c5e9 100644 --- a/website/docs/guides/markdown-features/markdown-features-head-metadata.mdx +++ b/website/docs/guides/markdown-features/markdown-features-head-metadata.mdx @@ -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 ``, `` and `` for you. It is possible to add extra metadata (or override existing ones) with the `` tag in Markdown files: @@ -42,10 +44,12 @@ My text ``` -:::tip - This `` 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 [``](./../../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 [``](./../../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**. +``` diff --git a/website/docs/guides/markdown-features/markdown-features-headings.mdx b/website/docs/guides/markdown-features/markdown-features-headings.mdx deleted file mode 100644 index a4beb7bba3fe..000000000000 --- a/website/docs/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/docs/guides/markdown-features/markdown-features-inline-toc.mdx b/website/docs/guides/markdown-features/markdown-features-toc.mdx similarity index 55% rename from website/docs/guides/markdown-features/markdown-features-inline-toc.mdx rename to website/docs/guides/markdown-features/markdown-features-toc.mdx index 09e78d7447ac..1cf45f32db1f 100644 --- a/website/docs/guides/markdown-features/markdown-features-inline-toc.mdx +++ b/website/docs/guides/markdown-features/markdown-features-toc.mdx @@ -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 +``` + +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'; ``` -## 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'; ``` +## 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#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 +
+Some details containing headings +

I'm a heading that will be not show up in the TOC

+ +Some content... + +
+``` + +The ability to 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 diff --git a/website/sidebars.js b/website/sidebars.js index 99f079461515..aa139632d171 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -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', diff --git a/website/static/_redirects b/website/static/_redirects index 1c1072d3227b..c30d7176c21c 100644 --- a/website/static/_redirects +++ b/website/static/_redirects @@ -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 From a9d24b4b5bb2373fd687bd29b90277e3c8c9d74c Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Sat, 30 Apr 2022 20:58:22 +0800 Subject: [PATCH 2/3] fix --- website/docs/cli.md | 2 +- .../docs/guides/markdown-features/markdown-features-react.mdx | 2 +- .../docs/guides/markdown-features/markdown-features-toc.mdx | 4 ++-- website/docs/i18n/i18n-tutorial.md | 2 +- website/docs/migration/migration-manual.md | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/website/docs/cli.md b/website/docs/cli.md index 530c55c7a49f..d1bec4d09ce4 100644 --- a/website/docs/cli.md +++ b/website/docs/cli.md @@ -171,7 +171,7 @@ By default, the files are written in `website/i18n//...`. ### `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 | | --- | --- | --- | diff --git a/website/docs/guides/markdown-features/markdown-features-react.mdx b/website/docs/guides/markdown-features/markdown-features-react.mdx index 230d5888ef68..1c6ff95a7cfb 100644 --- a/website/docs/guides/markdown-features/markdown-features-react.mdx +++ b/website/docs/guides/markdown-features/markdown-features-react.mdx @@ -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 diff --git a/website/docs/guides/markdown-features/markdown-features-toc.mdx b/website/docs/guides/markdown-features/markdown-features-toc.mdx index 1cf45f32db1f..4c5cc32bb9c2 100644 --- a/website/docs/guides/markdown-features/markdown-features-toc.mdx +++ b/website/docs/guides/markdown-features/markdown-features-toc.mdx @@ -126,14 +126,14 @@ Non-markdown headings will not show up in the TOC. This can be used to your adva ```md
Some details containing headings -

I'm a heading that will be not show up in the TOC

+

I'm a heading that will not show up in the TOC

Some content...
``` -The ability to 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). +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). --- diff --git a/website/docs/i18n/i18n-tutorial.md b/website/docs/i18n/i18n-tutorial.md index 2fa6975c75bc..c8e051ab3258 100644 --- a/website/docs/i18n/i18n-tutorial.md +++ b/website/docs/i18n/i18n-tutorial.md @@ -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)**. ::: diff --git a/website/docs/migration/migration-manual.md b/website/docs/migration/migration-manual.md index 5298838992e1..a10451db78a2 100644 --- a/website/docs/migration/migration-manual.md +++ b/website/docs/migration/migration-manual.md @@ -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} From 393b017d12871a796215c34640c11e17afd87b0e Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Sat, 30 Apr 2022 21:19:02 +0800 Subject: [PATCH 3/3] fix --- website/docs/guides/markdown-features/markdown-features-toc.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/guides/markdown-features/markdown-features-toc.mdx b/website/docs/guides/markdown-features/markdown-features-toc.mdx index 4c5cc32bb9c2..18e2d5d17614 100644 --- a/website/docs/guides/markdown-features/markdown-features-toc.mdx +++ b/website/docs/guides/markdown-features/markdown-features-toc.mdx @@ -119,7 +119,7 @@ import TOCInline from '@theme/TOCInline'; 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#details) will not be excluded. +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.