Skip to main content

ドキュメントを作成する

Markdown ファイル greeting.md を作成し、docs ディレクトリーの配下に配置しましょう。

website # あなたのサイトのルートディレクトリー
├── docs
│   └── greeting.md
├── src
│   └── pages
├── docusaurus.config.js
├── ...
---
description: リッチなコンテンツを含むドキュメントを作成する
---

# Docusaurus へようこそ

オープンソースプロジェクトのドキュメンテーションサイトを作成する用意はいいですか？

## ヘッダー

は、右上の目次に表示されます。

このページがどんなページなのか把握したいユーザーが、下へスクロールしたり、本文をたくさん読んだりしなくていいようにするためです。

## デフォルトでは h2 と h3 のみが目次に載ります。

目次の見出しレベルは、ドキュメントごとに設定するか、テーマ設定から設定できます。

ヘッダーは、階層を明確にするためのスペースでよく整理されています。

- lists will help you
- present the key points
- that you want your users to remember
  - and you may nest them
    - multiple times
メモ

docs ディレクトリー配下で、名前の先頭にアンダースコア（ _ ）が付いたすべてのファイルは「部分的な」ページとして扱われ、デフォルトでは無視されます。

詳しくは、部分ページのインポート をご覧ください。

ドキュメントのフロントマター（前付け）​

フロントマター（前付け） は、あなたのドキュメントページについて、追加のメタデータを提供するために使用されます。 フロントマターの記載は任意であり、Docusaurus では、フロントマター無しでもすべての必須なメタデータを推論できます。 For example, the doc tags feature introduced below requires using front matter. 使用できるすべての項目については、API ドキュメント を参照してください。

ドキュメントタグ​

Tags are declared in the front matter and introduce another dimension of categorization in addition to the docs sidebar.

It is possible to define tags inline, or to reference predefined tags declared in a tags file (optional, usually docs/tags.yml).

In the following example:

  • docusaurus references a predefined tag key declared in docs/tags.yml
  • Releases is an inline tag, because it does not exist in docs/tags.yml
docs/my-doc.md
---
tags:
  - Releases
  - docusaurus
---

# Title

Content
docs/tags.yml
docusaurus:
  label: 'Docusaurus'
  permalink: '/docusaurus'
  description: 'Docs related to the Docusaurus framework'
ヒント

タグの定義は、tags: [デモ, 作業の開始] のように記述することもできます。

詳しくは、使用できるすべての YAML 配列構文 をご覧ください。

フォルダ構造を整理する​

docs フォルダ下での Markdown ファイルの配置は、Docusaurus のコンテンツ生成に様々な影響を及ぼします。 ですが、そうした影響のほとんどはファイル構造から分離することができます。

ドキュメント ID​

すべてのドキュメントには固有の id があります。 デフォルトでは、ドキュメント id は、docs のルートディレクトリから見たドキュメントの名前です（拡張子は除く）。

例えば、greeting.md の ID は greeting、guide/hello.md の ID は guide/hello です。

website # あなたのサイトのルートディレクトリー
└── docs
   ├── greeting.md
   └── guide
      └── hello.md

ただし、id の末尾は、ユーザーがフロントマターで定義できます。 例えば、guide/hello.md の内容が以下のように定義されている場合、その id は最終的に guide/part1 になります。

---
id: part1
---

ダミーの本文です。

ID が使われるのは、サイドバーを手動作成する際のドキュメントへの参照や、ドキュメントに関連付けられたコンポーネントやフックの使用時です。

ドキュメント URL​

By default, the document's URL location is derived from the document id, which in turn is based on the document's file path.

If a file is named one of the following, the file name won't be included in the URL:

  • ファイル名が index（大文字・小文字を区別しない）であるもの：例 docs/Guides/index.md
  • ファイル名が README（大文字・小文字を区別しない）であるもの：例 docs/Guides/README.mdx
  • 親フォルダと同じ名前のファイル：例 docs/Guides/Guides.md

In all cases, the default slug would only be /Guides, without the /index, /README, or duplicate /Guides segment.

メモ

This convention is exactly the same as the category index convention. However, the isCategoryIndex configuration does not affect the document URL.

Use the slug front matter to provide an explicit document URL and override the default one.

For example, suppose your site structure looks like this:

website # あなたのサイトのルートディレクトリー
└── docs
    └── guide
        └── hello.md

By default, hello.md will be available at /docs/guide/hello. You can change its URL location to /docs/bonjour:

---
slug: /bonjour
---

ダミーの本文です。

slug will be appended to the doc plugin's routeBasePath, which is /docs by default. See Docs-only mode for how to remove the /docs part from the URL.

メモ

It is possible to use:

  • absolute slugs: slug: /mySlug, slug: /...
  • relative slugs: slug: mySlug, slug: ./../mySlug...
ヒント

Changing a document's filename or id, will change its default URL. To prevent breaking permalinks when renaming files, we recommend setting an explicit slug to keep your URLs stable.

Making a document available at the root​

あるドキュメントをルートで表示できるようにして、https://docusaurus.io/docs/ のようなパスを与えたい場合、slug フロントマターが使用できます。

---
id: my-home-doc
slug: /
---

ダミーの本文です。

自動生成のサイドバー を使用すると、サイドバーの構造はファイル構造によって決定されます。

ファイルシステムの整理について、以下のことが推奨されます。ファイルシステムはサイドバーの構造と一致させましょう（そうすると sidebars.js ファイルを手書きする必要が無くなります）。また、各ドキュメントの URL をカスタマイズするには slug フロントマターを使用しましょう。