Docusaurusを始める

Docusaurusとは

• ドキュメントサイトを作れるツール。
• Markdownでドキュメントを書く → Docusaurusで静的HTMLを生成 → ホスティングという流れで使う。
• バージョンごとのドキュメント、国際化、検索、ダークモード、テーマのカスタマイズに対応している。
• Reactベースで作れている。
• Facebookが作っているOSS。
• 競合ツールとしては次がある
  • GitBook
  • honkit
  • MkDocs
  • docsify

Docusaurusを試す

インストールと起動

Node.jsをインストールした環境で次のコマンドを実行する:

npx @docusaurus/init@latest init my-website classic

my-websiteにコードが生成されるので、そこへ行き開発サーバーを起動する:

cd my-website
npx docusaurus start

起動するとサイトがブラウザに表示される。

ページを作る

Docusaurusでは、src/pagesにファイルを作るとそれがページになるという仕様になっている。ファイルとURLの関係は次のようになる。

• src/pages/index.js -> localhost:3000/
• src/pages/foo.md -> localhost:3000/foo
• src/pages/foo/bar.js -> localhost:3000/foo/bar

Reactコンポーネントでページを作る

ためしに、Reactコンポーネントでページを作ってみよう。src/pages/my-react-page.jsにファイルを作り、内容は次のようにする。

import React from 'react';
import Layout from '@theme/Layout';

export default function MyReactPage() {
  return (
    <Layout>
      <h1>My React page</h1>
      <p>This is a React page</p>
    </Layout>
  );
}

ファイルを保存したら、http://localhost:3000/my-react-pageにアクセスする。すると、たった今作ったページが表示される。

Markdownでページを作る

今度はMarkdownでベージを作ってみよう。src/pages/my-markdown-page.mdにファイルを作り、内容は次のようにする:

# My Markdown page

This is a Markdown page

作ったページはhttp://localhost:3000/my-markdown-pageを開くと見れる。

ドキュメントページを作る

ドキュメントページは上で作った普通のページとは異なり、次のような特徴が出る:

• サイドバー(目次)に表示される
• 前後ページのナビゲーションのがつく
• バージョニングできる

ドキュメントページをMarkdownで作る

docs/hello.mdに次の内容でファイルを作る:

# Hello

This is my **first Docusaurus document**!

このページはhttp://localhost:3000/docs/helloにアクセスすると見れる。

サイドバーをカスタマイズする

frontmatterを設定すると、サイドバーに表示されるページタイトルを任意に変更できる。

---
sidebar_label: 'Hi!'
sidebar_position: 3
---

# Hello

This is my **first Docusaurus document**!