3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-04-29 02:08:36 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs: enhance docs about Markdown TOC and metadata (#7278)

Browse source 
* docs: multiple documentation improvements

* fix

* fix
This commit is contained in:
Joshua Chen 2022-04-30 21:30:14 +08:00 • committed by GitHub
parent afc72480ab
commit 9fd5d62340
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
11 changed files with 129 additions and 84 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
project-words.txt
View file

@ -311,6 +311,7 @@ typedoc
typesense
unflat
unist
unlinkable
unlocalized
unmatch
unnormalized

2
website/docs/cli.md
View file

@ -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 |
| --- | --- | --- |

8
website/docs/guides/docs/sidebar/autogenerated.md
View file

@ -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">

34
website/docs/guides/markdown-features/markdown-features-head-metadata.mdx
View file

@ -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**.
```

57
website/docs/guides/markdown-features/markdown-features-headings.mdx
View file

@ -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 to="#heading-id">link</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.
:::

2
website/docs/guides/markdown-features/markdown-features-react.mdx
View file

@ -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

92
website/docs/guides/markdown-features/markdown-features-inline-toc.mdx → website/docs/guides/markdown-features/markdown-features-toc.mdx
View file

@ -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
## Full table of contents {#full-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}
```
:::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

2
website/docs/i18n/i18n-tutorial.md
View file

@ -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)**.
:::

2
website/docs/migration/migration-manual.md
View file

@ -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}

3
website/sidebars.js
View file

@ -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',

10
website/static/_redirects
View file

@ -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