Docusaurusはドキュメントサイトを作るために使われるケースが多いです。今回は、Docusaurusでドキュメントページを作成する方法を解説します。
ドキュメントのページは最もよく作られる、基本的なページのため今回の内容は非常に重要です。
ドキュメントページを作成
docs/ ディレクトリに greeting.md というマークダウンファイルを作成します。
website # サイトのルートディレクトリ
├── docs
│ └── greeting.md
├── src
│ └── pages
├── docusaurus.config.js
├── ...
greeting.md
---
description: ドキュメントページ作成
tags:
- Releases
- docusaurus
---
# Docusaurus
オープンソース プロジェクトのドキュメント サイトを作成する準備はできていますか?
## ヘッダー
ヘッダーが右上の目次に表示され、このページの構成を把握できます。
## デフォルトでは、h2 と h3 のみが TOC（目次）に含まれます
TOCの見出しレベルは、ドキュメントごとに、またはテーマ設定で設定できます。
階層が明確になるように、ヘッダーの間隔が広く取られています。
- マークダウンでリストを記述できます
- リストはネストして
- 複数回
- 使用できます。
npm run start でローカルのサーバーを起動し、http://localhost:3000/docs/greeting にアクセスすると以下のようなページが表示されます。
アンダースコア (_) から始まるファイル名は「部分」ページとして扱われ、デフォルトでは無視されます（ページのURLは作成されません）
ドキュメントの front matter
front matter はドキュメント ページに追加のメタデータを提供するために使用されます。front matter はオプションです。
例えば、以下で紹介するタグ付け機能では、front matter を使用する必要があります。
タグ付け
タグは front matter で宣言され、docs サイドバー に加えて別の分類が導入されます。
タグをインラインで定義したり、tags file で宣言された事前定義タグを参照したりすることができます。このタグ付け機能はオプションで、通常は docs/tags.yml で定義します。
以下の例では:
- docusaurusは、docs/tags.yml で宣言された事前定義タグキーを参照します
- Releases タグは、docs/tags.yml には存在しないため、インラインタグになります。
docs/my-doc.md
---
tags:
- Releases
- docusaurus
---
# タイトル
内容
docs/tags.yml
docusaurus:
label: 'Docusaurus'
permalink: '/docusaurus'
description: 'Docusaurus フレームワークに関連するドキュメント'
赤線の部分はtags.ymlで定義した内容です。
tags: [Demo, Getting started] のように宣言することもできます。
ドキュメント ID
すべての文書には一意のIDがあります。デフォルトでは、ドキュメントIDはdocsディレクトリに対するドキュメントの名前（拡張子を除く）です。
例えば、greeting.mdのIDは、greeting になります。guide/hello.md のIDは、 guide/hello になります。
website # サイトのルートディレクトリ
└── docs
├── greeting.md
└── guide
└── hello.md
IDの最後の部分は、front matter で定義することもできます。
例えば、guide/hello.md に以下ように定義されている場合、IDは、guide/part1 になります。
---
id: part1
---
IDは、サイドバーを自作する場合や、ドキュメント関連のレイアウト コンポーネントやフックを使用する場合に、ドキュメントを参照するために使用されます。
ドキュメントの URL
デフォルトでは、ドキュメントのURL位置は、docsフォルダーを基準としたファイルパスです。ただし、ファイルに次の名前が付けられている場合、そのファイル名は URL に含まれません
- index（大文字と小文字を区別しません）: docs/Guides/index.md
- README（大文字と小文字を区別しません）: docs/Guides/README.mdx
- 親フォルダと同じ名前: docs/Guides/Guides.md
すべての場合において、デフォルトのスラッグは、/Guides になります。（/Guides/index、/Guides/README、/Guides/Guides ではありません）
slug という front matter を使って URL を変更することができます。
たとえば、サイト構造は次のようになるとします。
website # サイトのルートディレクトリ
└── docs
└── guide
└── hello.md
デフォルトでは hello.md のURLは、 /docs/guide/hello ですが、以下のように hello.md にslugを定義すると、URLを /docs/bonjour に変更できます。
---
slug: /bonjour
---
slug は、ドキュメントのプラグインの routeBasePath （デフォルトは /docs）に追加されます。
メモ
slug は、２通りの書き方ができます。
絶対パスで書く方法 slug: /mySlug、 slug: /…
相対パスで書く方法 slug: mySlug、 slug: ./../mySlug…
ドキュメントをルートで利用できるようにし、https://docusaurus.io/docs/ のようなパスを持たせたい場合、slug の front matter を使用することができます。
---
id: my-home-doc
slug: /
---
サイドバー
サイドバーの自動生成を使用すると、ファイル構造によりサイドバーが自動的に決定します。
よって、ディレクトリ構成をサイドバーの構造と同じにすることをお勧めします。
