本文へスキップ
バージョン: 3.5.2

Markdown 機能

Docusaurus は主要なコンテンツ作成形式としてMarkdown を使用しています。

Markdown の学習

10 分で Markdown を学習できます。10 分で Markdown を学ぶ

Docusaurus は、最新のツールを使用してインタラクティブなドキュメントの作成を支援します。

MDX コンパイラはMarkdown ファイルを React コンポーネントに変換し、Markdown コンテンツ内で JSX を使用できるようにします。これにより、コンテンツ内に React コンポーネントを簡単に挿入し、魅力的な学習エクスペリエンスを作成できます。

MDX プレイグラウンドの使用

MDX プレイグラウンド はあなたの新しい最高の友達です！

これは、MDX コンパイラが Markdown を React に変換する方法を示す、非常に役立つデバッグツールです。

オプション：適切な形式（MDX または CommonMark）と、Docusaurus が使用する次のプラグインを選択します。`remark-gfm`、`remark-directive`、`rehype-raw`。

MDX 対 CommonMark​

Docusaurus は MDX コンパイラを使用して `.md` ファイルと `.mdx` ファイルの両方を React コンポーネントにコンパイルしますが、構文は設定によって異なる解釈がされる可能性があります。

MDX コンパイラは2 つの形式をサポートしています。

  • MDX 形式：JSX の使用を可能にする強力なパーサー
  • CommonMark 形式：JSX の使用を許可しない、標準準拠の Markdown パーサー

デフォルトでは、Docusaurus v3 は、歴史的な理由からすべてのファイル（`.md` ファイルを含む）に MDX 形式を使用します。

siteConfig.markdown.format 設定または `format: md` フロントマターを使用して、CommonMark を選択できます。

CommonMark の使用方法

CommonMark を使用する場合、siteConfig.markdown.format: 'detect' 設定をお勧めします。ファイル拡張子に基づいて、適切な形式が自動的に選択されます。

  • `.md` ファイルは CommonMark 形式を使用します。
  • `.mdx` ファイルは MDX 形式を使用します。
実験的な CommonMark サポート

CommonMark のサポートは実験的であり、現在いくつかの制限事項があります。

標準機能​

Markdown は、読みやすい構文でフォーマットされたコンテンツを作成できる構文です。

### My Doc Section

Hello world message with some **bold** text, some _italic_ text, and a [link](/)

![img alt](/img/docusaurus.png)
http://localhost:3000

マイ ドキュメント セクション

いくつかの太字テキスト、いくつかの斜体テキスト、およびリンクを含む、Hello world メッセージ

img alt

Markdown は宣言的です

Markdown と HTML の間に 1 対 1 の相関関係があると仮定する人もいますが、たとえば、`![Preview](/img/docusaurus.png)` は常に `<img src="/img/docusaurus.png" alt="Preview" />` になるわけではありません。しかし、そうではありません。

Markdown 構文 `![message](url)` は、ここに画像を挿入する必要があることを Docusaurus に宣言的に伝えるだけです。しかし、ファイルパスを URL パスに変換するなど、他の処理を行う場合があり、生成されたマークアップは他の Markdown レンダラーの出力や、同等の JSX/HTML コードへの単純な手書き転記とは異なる場合があります。

一般的に、マークアップのセマンティクス（````` フェンスはコードブロックになります。`>` は引用になりますなど）だけを仮定する必要がありますが、実際のコンパイル済み出力は仮定しないでください。

フロントマター​

フロントマターは、Markdown ファイルにメタデータを追加するために使用されます。すべてのコンテンツプラグインには独自のフロントマタースキーマがあり、フロントマターを使用して、コンテンツまたは他の設定から推測されたデフォルトのメタデータに追加情報を付け加えます。

フロントマターはファイルの一番上にあり、3 つのダッシュ `---` で囲まれています。コンテンツはYAMLとして解析されます。

---
title: My Doc Title
more_data:
  - Can be provided
  - as: objects
    or: arrays
---
情報

各公式プラグインの API ドキュメントには、サポートされている属性がリストされています。

フロントマターの拡張

Markdown 設定の `parseFrontMatter` 関数 を使用して、独自のフロントマターパーサーを提供するか、デフォルトのパーサーを拡張できます。

独自の独自のロジックでラップするために、デフォルトのパーサーを再利用できます。これにより、便利なフロントマター変換、ショートカットを実装したり、Docusaurus プラグインがサポートしていないフロントマターを使用して外部システムと統合したりできます。

docusaurus.config.js
export default {
  markdown: {
    parseFrontMatter: async (params) => {
      // Reuse the default parser
      const result = await params.defaultParseFrontMatter(params);

      // Process front matter description placeholders
      result.frontMatter.description =
        result.frontMatter.description?.replaceAll('{{MY_VAR}}', 'MY_VALUE');

      // Create your own front matter shortcut
      if (result.frontMatter.i_do_not_want_docs_pagination) {
        result.frontMatter.pagination_prev = null;
        result.frontMatter.pagination_next = null;
      }

      // Rename an unsupported front matter coming from another system
      if (result.frontMatter.cms_seo_summary) {
        result.frontMatter.description = result.frontMatter.cms_seo_summary;
        delete result.frontMatter.cms_seo_summary;
      }

      return result;
    },
  },
};

引用​

Markdown の引用は美しくスタイル設定されています。

> Easy to maintain open source documentation websites.
>
> — Docusaurus
http://localhost:3000

メンテナンスが容易なオープンソースのドキュメント Web サイト。

— Docusaurus

詳細​

Markdown は HTML 要素を埋め込むことができ、details HTML 要素は美しくスタイル設定されています。

### Details element example

<details>
  <summary>Toggle me!</summary>

  This is the detailed content

  ```js
  console.log("Markdown features including the code block are available");
  ```

  You can use Markdown here including **bold** and _italic_ text, and [inline link](https://docusaurus.dokyumento.jp)
  <details>
    <summary>Nested toggle! Some surprise inside...</summary>

    😲😲😲😲😲
  </details>
</details>
http://localhost:3000

details 要素の例

切り替え！

これが詳細なコンテンツです。

console.log("Markdown features including the code block are available");

Markdownを使用できます。**太字**や斜体のテキスト、そしてインラインリンクも使用可能です。

ネストされたトグル！中に何かサプライズが…

😲😲😲😲😲

情報

<summary>は1行に収めておくことをお勧めします。 MDXは改行のために余分なHTML <p>段落を作成することに注意してください。 不明な点がある場合は、MDXプレイグラウンドを使用して<details>のレンダリングの問題をトラブルシューティングしてください。