Skip to main content

見出しと目次

Markdown headings​

You can use regular Markdown headings.

## Level 2 title

### Level 3 title

#### Level 4 title

Markdownの各見出しは、目次の項目として表示されます。

見出しID​

各見出しにはIDがあり、自動生成または明示的に指定することができます。 見出しIDによって、以下のようなMarkdownやJSXで特定の文書の見出しにリンクすることができます。

[link](#heading-id)
<Link to="#heading-id">link</Link>

デフォルトでは、Docusaurusは見出しのテキストに基づいて見出しIDを生成します。 For example, ### Hello World will have ID hello-world.

Generated IDs have some limitations:

  • IDの見た目が悪い場合がある
  • You might want to change or translate the text without updating the existing ID to avoid breaking links

A special syntax lets you set an explicit heading id.

### Hello World {/* #my-explicit-id */}

### Hello World {#my-explicit-id}

The heading id comment must start with #, be placed at the end of the heading and will be stripped from the rendered output.

ヒント

Use the write-heading-ids CLI command to add explicit IDs to all your Markdown documents.

The --syntax option lets you choose which syntax you prefer:

  • The classic syntax for {#headingId}
  • The mdx-comment syntax for {/* #headingId */}
Avoid the classic {#id} syntax for MDX files

For MDX files, the {#id} syntax should be avoided. Since Docusaurus v3 and MDX v2, it is not valid MDX syntax anymore. It can break external tools that support MDX (IDEs and linters). It is only supported in Docusaurus for backward compatibility, thanks to the markdown.mdx1Compat.headingIds config option. The comment-based syntax should be preferred for MDX documents.

Avoid colliding IDs

生成された見出しIDは各ページで一意であることが保証されますが、カスタムIDを使用する場合は、それぞれが各ページに1つだけあるようにしてください。そうしないと、同じIDを持つ2つのDOM要素が存在することになりますが、これは無効なHTMLセマンティクスであり、一つの見出しがリンク不能となることに繋がります。

目次の見出しレベル​

各Markdownドキュメントには、右上に目次が表示されます。 デフォルトでは、この目次にはh2およびh3の見出しのみが表示されますが、ページ構造の概要を知るには十分でしょう。 見出しの表示範囲を変更する必要がある場合、最小および最大の見出しレベルをページごとまたはグローバルにカスタマイズすることができます。

To set the heading level for a particular page, use the toc_min_heading_level and toc_max_heading_level front matter.

myDoc.md
---
# h2〜h5の見出しを表示
toc_min_heading_level: 2
toc_max_heading_level: 5
---

To set the heading level for all pages, use the themeConfig.tableOfContents option.

docusaurus.config.js
export default {
  themeConfig: {
    tableOfContents: {
      minHeadingLevel: 2,
      maxHeadingLevel: 5,
    },
  },
};

全体オプションを設定した場合でも、フロントマターによって局所的に上書きすることができます。

メモ

The themeConfig option would apply to all TOC on the site, including inline TOC, but front matter options only affect the top-right TOC. You need to use the minHeadingLevel and maxHeadingLevel props to customize each <TOCInline /> component.

インラインの目次​

また、MDXの利用により、Markdown文書内に直接目次を表示することもできます。

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.

import TOCInline from '@theme/TOCInline';

<TOCInline toc={toc} />
http://localhost:3000

The toc global is just a list of heading items:

declare const toc: {
  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.

import TOCInline from '@theme/TOCInline';

<TOCInline
  // Only show h2 and h4 headings
  toc={toc.filter((node) => node.level === 2 || node.level === 4)}
  minHeadingLevel={2}
  // Show h4 headings in addition to the default h2 and h3 headings
  maxHeadingLevel={4}
/>
http://localhost:3000

目次の生成をカスタマイズ​

The table-of-contents is generated by parsing the Markdown source with a Remark plugin. 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 and 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.

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

警告

Below is just some dummy content to have more table of contents items available on the current page.

セクション 1 の例​

Lorem ipsum

例 サブセクション 1 a​

Lorem ipsum

例サブセクション 1 a I​

例サブセクション 1 a II​

Example subsubsection 1 a III​

Example Subsection 1 b​

Lorem ipsum

Example subsubsection 1 b I​

Example subsubsection 1 b II​

Example subsubsection 1 b III​

Example Subsection 1 c​

Lorem ipsum

Example subsubsection 1 c I​

Example subsubsection 1 c II​

Example subsubsection 1 c III​

例：セクション 2​

Lorem ipsum

例：サブセクション 2 a​

Lorem ipsum

例：サブサブセクション 2 a I​

例：サブサブセクション 2 a II​

例：サブサブセクション 2 a III​

例：サブセクション 2 b​

Lorem ipsum

​

例：サブサブセクション 2 b II​

Example subsubsection 2 b III​

Example Subsection 2 c​

Lorem ipsum

Example subsubsection 2 c I​

Example subsubsection 2 c II​

Example subsubsection 2 c III​

Example Section 3​

Lorem ipsum

例：サブセクション 3 a​

Lorem ipsum

例：サブサブセクション 3 a I​

例：サブサブセクション 3 a II​

例：サブサブセクション 3 a III​

例：サブセクション 3 b​

Lorem ipsum

例：サブサブセクション 3 b I​

例：サブサブセクション 3 b II​

例：サブサブセクション 3 b III​

例：サブセクション 3 c​

Lorem ipsum

例：サブサブセクション 3 c I​

例：サブサブセクション 3 c II​

例：サブサブセクション 3 c III​