マークダウンで簡単にサイト作成 - Docusaurusの使い方

はじめに

マークダウンファイルからサイトを生成する静的サイトジェネレータのDocusaurusの基本的な使い方をご紹介します。

Docusaurusは、情報量の多いマニュアルサイトの作成する際に重宝するツールです。

---

Docusaurusとは

概要

Docusaurus（ドキュザラス）は、Facebookが開発しているドキュメントサイト作成ツールで、Facebook社のオープンソースソフトウェアのプロジェクトのためのツールとして開発されました。

そのため、現在もDocusaurusはオープンソースプロジェクトのサイトを構築、維持するためのツールとして開発されています。

Docusaurusは、v1とv2があります。

v2はまだβ版ですが、新たにDocusaurusを使う方はv2の利用が推奨されています。
本記事でもv2の使い方を説明します。

なお、既にv1を利用している方向けには移行ガイドも公開されています。

v1 to v2 migration guide
Migration overview | Docusaurus

公式サイト
Build optimized websites quickly, focus on your content | Docusaurus

特徴

Docusaurusには、以下の特徴があります。

• 静的サイトジェネレータ（Static Site Generator）である
• ドキュメントサイトの構築が得意
• マークダウンファイルを静的サイトに変換してくれる
• Reactをサポートしている
• 多言語化サイト用の機能がある
• ドキュメントのバージョン管理機能がある
• サイト内検索機能（Algolia documentation search）をサポートしている
• デプロイ機能がある

なお、ドキュメントサイトの構築向けツールではあるものの、ホームページ（トップページ）や会社概要などの独立したページ（WordPressでいう固定ページ）、ブログページなども作成することが可能です。

マニュアルを作る際に重宝します

Docusaurusは、ある程度ボリュームのある社内外向けのマニュアルを作る際に重宝します。

私は数年前までは、取扱説明書などはPowerPointやWord、あるいはプレーンなテキストファイルで作成していたのですが、最近はDocusaurusを使うか、他のマークダウンをサポートしているツールで作成する事が多くなってきました。

理由は、圧倒的に制作時間が短縮できる事と、修正や更新といったメンテナンスが容易である事、NotionなどのWebサービスに依存しない点が挙げられます(Notionも重宝していますが)。

Docusaurus以外では、Stack EditやPandocを利用しています。いずれもマークダウンファイルを目次付きでHTMLファイルに変換してくれます。

1ページで完結できるマニュアルの場合はStack EditかPandocを使用します。

これらの解説に関しては以下の記事をご覧ください。

参考記事
Markdownを素敵なHTMLに変換するツール3選

なお、Docusaurusの場合、こういったマニュアルは、関係のない方には見られたくないため、IPアドレスによるアクセス制限やBasic認証、noindexのメタタグ挿入などの対策を行っています。

StackEditやPandocの場合は、変換したHTMLファイルや画像ファイル一式をそのまま関係者に渡して各々のマシンで閲覧してもらえれば良いのですが、Docusaurusの場合はローカルで閲覧する場合でもウェブサーバーが立ち上がっている必要があります。

これはDocusaurusを扱う際の注意点として挙げられますね。

利用方法

この記事で構築するもの

本記事では、基本的なドキュメントサイトの構築手順を解説します。
本記事の手順を踏むと、2カラムのドキュメントサイトを、素早く構築できるようになります。

Docusaurusの機能としてはDocsを利用します。PagesやBlogsは利用しません。 これは、公式のドキュメントではDocs-only modeと呼ばれています。

前提条件

バージョン12.13.0以上のNode.jsをインストールしておいてください。

Yarnも利用可能で、その場合は、バージョン1.5以上をインストールしておく必要があります。

以下、公式サイトより引用 :

Node.js version >= 12.13.0 or above (which can be checked by running node -v). You can use nvm for managing multiple Node versions on a single machine installed
Yarn version >= 1.5 (which can be checked by running yarn --version). Yarn is a performant package manager for JavaScript and replaces the npm client. It is not strictly necessary but highly encouraged.

なお、本記事ではWindows環境での手順を記載しますが、masOSでも手順は同様です。

では、構築を進めて行きましょう。

作業フォルダを作る

まず、適当な作業用フォルダを作成してください。

ターミナルを立ち上げで、作業フォルダに移動する

ターミナルでディレクトリに移動します。

cd ディレクトリのパス

Docusaurusをインストールする

ターミナルでインストールします。

コマンドの構文は以下の通りです。

npx @docusaurus/init@latest init [name] [template]

nameは、プロジェクトフォルダの名前になります。ここで指定した名前のディレクトリが作成され、その中にDocusaurusがインストールされます。

templateは、Docusaurusのテンプレート名です。
Docusaurusの基本機能が網羅されていてカスタマイズしやすく、Docusaurus 1の機能も含まれているclassicの利用が推奨されています。

Facebookのオープンソースプロジェクトのためのサイトの場合はfacebook、Bootstrapを利用したサイトの場合はbootstrapのテンプレートが用意されているようです。

特に理由がなければclassicテンプレートで良いので、以下のコマンドを実行します。

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

my-websiteの名前は任意で変えてください。

インストール時に以下のメッセージが表示されるかもしれませんが、YesでOKです。

Need to install the following packages:
  @docusaurus/init@latest
Ok to proceed? (y)

ディレクトリ構造の解説

classicテンプレートをインストールすると、以下のようなディレクトリ構造でDocusaurusがインストールされます。

my-website
├── blog
│   ├── 2019-05-28-hola.md
│   ├── 2019-05-29-hello-world.md
│   └── 2020-05-30-welcome.md
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   └── mdx.md
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── styles.module.css
│       └── index.js
├── static
│   └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

各ディレクトリの役割は以下の通りです。

• /blog/ - ブログ記事用のディレクトリで、サンプルのマークダウンファイルが格納されています。ブログが不要な場合はこのディレクトリを削除します。
• /docs/ - ドキュメント用のディレクトリで、sんプルのマークダウンファイルが格納されています。sidebars.jsを編集することでドキュメントの順番等を変更できます。
• /src/ - ドキュメントサイトやReactのカスタマイズ用コンポーネント等以外のファイルを格納するディレクトリです。特に非ドキュメント用ファイルをここに置く必要があるという訳ではありませんが、それらのファイルをこのディレクトリに置いておく事でリンティングなどの処理を行う際に特定しやすいとのことです。
• /src/pages - このディレクトリに保存されるファイルはウェブサイトのページとして変換されます。Docusaurusインストール時のトップページもこのディレクトリに格納されています。WordPressで言う所の固定ページ用のディレクトリと言えます。
• /static/ - Docusaurusによって動的に変換されないファイルを格納するディレクトリです。画像などは、/static/img配下に格納します。/static/配下のコンテンツは、最終的にビルドされるディレクトリのルートディレクトリにそのままコピーされます。
• /docusaurus.config.js - サイトの設定を記述するファイルです。Docusaurus v1のsiteConfig.jsと同じ役割を担います。
• /package.json - npmパッケージが記述されているファイルです。追加でnpmパッケージをインストールして利用する事ができます。
• /sidebar.js - ドキュメントサイトのサイドバーに表示させる各ページの順番等を定義するファイルです。

以下、原文。

• /blog/ - Contains the blog Markdown files. You can delete the directory if you do not want/need a blog. More details can be found in the blog guide
• /docs/ - Contains the Markdown files for the docs. Customize the order of the docs sidebar in sidebars.js. More details can be found in the docs guide
• /src/ - Non-documentation files like pages or custom React components. You don't have to strictly put your non-documentation files in here but putting them under a centralized directory makes it easier to specify in case you need to do some sort of linting/processing
• /src/pages - Any files within this directory will be converted into a website page. More details can be found in the pages guide
• /static/ - Static directory. Any contents inside here will be copied into the root of the final build directory
• /docusaurus.config.js - A config file containing the site configuration. This is the equivalent of siteConfig.js in Docusaurus v1
• /package.json - A Docusaurus website is a React app. You can install and use any npm packages you like in them
• /sidebar.js - Used by the documentation to specify the order of documents in the sidebar

ドキュメントサイトで利用する主なディレクトリとファイルは以下の通りです。

my-website
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   └── mdx.md
├── static
│   └── img
├── docusaurus.config.js
└── sidebars.js

サイトを起動してみる

さて、Docusaurusのインストールが完了したら、ターミナルでインストール先のディレクトリに移動しましょう。

cd my-websiteまでのパス

次に、以下のコマンドを打ちます。

npm start

これでローカルにウェブサーバーが立ち上がり、http://localhost:3000/でサイトが表示されます。

---

なお、この間バッチ処理が行われており、ファイルが更新されるとブラウザがリロードされます。
ウェブサーバーを終了する時は以下のコマンドで終了させます。

Ctrl(Cmd) + C

ここからサイトをカスタマイズしていきます。

docsディレクトリをサイトのホームページにする

デフォルトの状態だと、/src/pages/index.jsのページがサイトのホームページ（トップページ）になります。

シンプルなドキュメントサイトの場合は、このページは不要になります。

今回は、docs配下のページのみでドキュメントサイトを構築していくため、サイトのホームページもdocsディレクトリ配下のページにします。

そのため、まずはdocusaurus.config.jsを開き、presetsの配下のdocsの配列に、以下を追加します。

routeBasePath: '/',

以下のsidebarPathの上に追記すればよいでしょう。

presets: [
 [
   '@docusaurus/preset-classic',
   {
     docs: {
       sidebarPath: require.resolve('./sidebars.js'),
       // Please change this to your repo.
       editUrl:
         'https://github.com/facebook/docusaurus/edit/master/website/',
     },
     blog: {
       showReadingTime: true,
       // Please change this to your repo.
       editUrl:
         'https://github.com/facebook/docusaurus/edit/master/website/blog/',
     },
     theme: {
       customCss: require.resolve('./src/css/custom.css'),
     },
   },
 ],
],

追記後は、docs配下は以下のようになります。

        docs: {
          routeBasePath: '/',
          sidebarPath: require.resolve('./sidebars.js'),
          // Please change this to your repo.
          editUrl:
            'https://github.com/facebook/docusaurus/edit/master/website/',
        },

次に、以下のディレクトリを削除します。

/src/pages/

デフォルトのトップページのみを削除する場合は以下のファイルを削除してください。

/src/pages/index.js

なお、サーバー起動中にこのディレクトリやファイルを削除するとブラウザにエラーメッセージが表示されるか、Page Not Foundが表示されます。

これは、デフォルトのトップページ /src/pages/index.js の代わりに利用したいトップページを指定できていないために発生しています。

これを解消するために、docsディレクトリにトップページ用のマークダウンファイルを作成し、URLを指定するslugを追加します。

例として、以下のファイルを作成します。

/my-website/docs/my-home.md

上記ファイルの冒頭に以下を記述します。

---
slug: /
---

これでトップページ http://localhost:3000/にアクセスすると、先ほど指定した/my-website/docs/my-home.mdが表示されます。

ここからさらに、docusaurus.config.jsを自身のサイト用にカスタマイズしていきます。

マニュアルサイトのリポジトリURLを記載する

ドキュメントサイトをGitでバージョン管理する場合は、リポジトリのURLを設定することができます。

この設定を行う事で、各ページに編集用リンクが付与され、クリックすると指定したリモートリポジトリへ直接アクセスできるようになります。

編集する箇所は、docusaurus.config.jsのpresetsの配下のdocsの配列にあるeditUrlです。

docs: {
  routeBasePath: '/',
  sidebarPath: require.resolve('./sidebars.js'),
  // Please change this to your repo.
  editUrl:
    'https://github.com/facebook/docusaurus/edit/master/website/',
},

ヘッダー・フッターを編集する

ヘッダーの編集

ヘッダーやフッター、ロゴ画像は、docusaurus.config.jsの中のthemeConfigを編集することで変更できます。

まずヘッダーナビゲーションは以下のnavbarオブジェクトを編集します。

ここで、表示されるテキストやサイト内のリンク、外部リンクなどを設定できます。

navbar: {
 title: 'My Site',
 logo: {
   alt: 'My Site Logo',
   src: 'img/logo.svg',
 },
 items: [
   {
     type: 'doc',
     docId: 'intro',
     position: 'left',
     label: 'Tutorial',
   },
   {to: '/blog', label: 'Blog', position: 'left'},
   {
     href: 'https://github.com/facebook/docusaurus',
     label: 'GitHub',
     position: 'right',
   },
 ],
},

試しに次のように変更してみます。

navbar: {
 title: 'ZATTA PRODUCTION DOCUMENTATION',
 logo: {
   alt: 'My Site Logo',
   src: 'img/siteLogo.svg',
 },
 items: [
   {
     type: 'doc',
     docId: 'home',
     position: 'left',
     label: 'Site Home',
   },
   {
     href: 'https://zatta.link/about/',
     label: 'ABOUT ZATTA PRODUCTION',
     position: 'right',
   },
 ],
},

ブログのリンクは不要なので以下の箇所は削除しました。

{to: 'blog', label: 'Blog', position: 'left'},

また、ロゴ画像 img/siteLogo.svg と、新たなドキュメント用ページ docs/home.mdを追加しています。

docs/home.mdには、以下を記述しています。

---
sidebar_position: 1
id: home
---

マークダウンファイルの書き方は後述します。 現時点では、何をしたのかだけ、把握しておけば大丈夫です。

これにより、ヘッダーが変更されました。

すると以下のようになります。

---

フッターとコピーライトの編集

ヘッダー同様に、footer、copyrightを書き換える事で変更可能です。

なお、サイトのホームページをdocs配下のファイルに変更してあるため、フッターのリンクが/docs/your-pageとなっている場合は、リンク切れが発生しますので、docsを削除する必要があります。

blogを削除する

/blog/ディレクトリは使用しないため、削除しましょう。

また、docusaurus.config.jsのblogの設定箇所も削除します。

blog: {
  showReadingTime: true,
  // Please change this to your repo.
  editUrl:
    'https://github.com/facebook/docusaurus/edit/master/website/blog/',
},

サイトの基本情報を編集する

サイトの基本的な情報は、docusaurus.config.jsの冒頭の以下の箇所で設定します。

title: 'My Site',
tagline: 'Dinosaurs are cool',
url: 'https://your-docusaurus-test-site.com',
baseUrl: '/',
onBrokenLinks: 'throw',
onBrokenMarkdownLinks: 'warn',
favicon: 'img/favicon.ico',
organizationName: 'facebook', // Usually your GitHub org/user name.
projectName: 'docusaurus', // Usually your repo name.

urlには、最終的にビルドしたファイルをアップロードするURLを入力してください。
ここを正しく入力しないとビルドした際にサイト内のリンクが正しく出力されません。

faviconもここで設定可能です。

organizationNameには通常GitHubの組織名かユーザー名を、projectNameにはリポジトリ名を入力するようです。

次から、ようやくドキュメント用のマークダウンファイルを作成していきます。

docsディレクトリ内に.mdファイルを作っていき、ページを作成していく

マークダウンファイルのメタ情報の構文

マークダウンファイルの冒頭には、以下の情報を入力します。

---
id: doc1
title: Style Guide
sidebar_label: Style Guide
sidebar_position: 1
---

各項目は以下の役割があります。

• id
  • 各ページユニークなID。
  • ページのURLになります。
  • 省略した場合は、拡張子を除いたファイル名がIDとなります。
  • docsディレクトリ配下にサブディレクトリを作成している場合は、IDはサブディレクトリを含むパスになります（例：sub-directory/your-name）
  • このIDはサイドバーにページを明示的に登録する際に利用します。
• title : ページタイトルです。ページの先頭にh1として表示されます。
• sidebar_label : 、左側のサイドバーに表示されるテキストです。
• sidebar_position: サイドバーの並びを指定するための番号です。この番号を指定することで、表示順を明示的に変更することができます。

なお、IDとURLを分けたい場合は、slugを指定します。

---
id: part1
slug: your-url.html
---

また、slugは絶対パスや相対パスでも指定できます。

絶対パスの場合は…

slug: /mySlug

相対パスの場合は…

slug: mySlug

slug: ./../mySlug...

となります。

サイドバーにページを登録する

マークダウンファイルから生成されるHTMLページには、デフォルトでは、docsディレクトリの構造に応じて、自動的にサイドバーに追加されていきます。

---

zatta-01というディレクトリとその配下のファイルをテスト用に作成しています。

自動生成の場合はsidebar.jsに以下のコードを記述します（初期値）。

module.exports = {
  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
};

一方で、任意の並びに編集する事も可能です。

いくつか記述方法がありますので、記載します。

まずは基本的な構文です。

module.exports = {
  mySidebar: [
    {
      type: 'category',
      label: 'Heading 01',
      items: ['intro'],
    },
    {
      type: 'category',
      label: 'Heading 02',
      items: ['home', 'zatta-01/zatta'],
    },
  ],
};

これによりサイドバーが以下のように表示されます。

---

ショートハンドもあり、以下のように短いコードで記述も可能です。

module.exports = {
 mySidebar: {
  Heading 01: [
  'home',
  'zatta-01/zatta',
  ],
  Heading 02: [
  'intro'
  ],
 },
};

閲覧しているページに応じて、表示させるサイドバーを変更する事もできます。

以下の記述では、homeとzatta-01/zattaのページを閲覧時はmySidebar01を表示し、introを閲覧時はmySidebar02を表示させる事ができます。

mySidebar01: {
 'Category A': [
 'home',
 'zatta-01/zatta',
 ],
 'Category B': [
 'home',
 'zatta-01/zatta',
 ],
},
mySidebar02: ['intro'],

マークダウンファイルの装飾方法

概要

Docusaurusは一般的なマークダウン記法をサポートしています。

マークダウン記法はこちらの記事を参照ください。

Daring Fireball: Markdown Syntax Documentation

リンク

リンクは、URLパス、ファイルへの相対パスのどちらもサポートしています。

以下に例を記載します。

[Create a page](/create-a-page)

[Create a page](./create-a-page.md)

拡張子を含めたファイルパスを記述した場合、.mdの拡張子はリンクから取り除かれます。

なお、前述の通り、ファイル内でidを指定している場合は、ファイル名ではなくidがURLとして優先されますのでご注意下さい。

画像

画像はstatic/img/ディレクトリに格納していきますが、リンクを作成する際はstaticディレクトリを除外したパスを指定します。

以下に例を記載します。

![Docusaurus logo](/img/docusaurus.png)

imgディレクトリ配下はサブディレクトリで整理しても問題ありません。

コードブロック

コードブロックはシンタックスハイライトをサポートしています。
コードブロックの始まりの ``` の後に、コードブロック内に記述する言語を指定するとコードがハイライトされます。

例えば、コードブロック内にCSSを記述したい場合は、 ```css と記述します。

アラートボックス / Admonitions

Docusaurus独自の記法として、Admonitions(アドモニション/警告)コンポーネントが用意されています。

アラートボックスのようなもので、以下のように記述することで、色々な種類のボックスを生成できます。

:::note
Your message here.
:::

:::danger
Your message here.
:::

:::tip
Your message here.
:::

:::info
Your message here.
:::

:::caution
Your message here.
:::

それぞれ、以下のように表示されます。

---

また、以下のように記述する事で、任意のタイトルを付ける事ができます。

:::note YOUR TITLE
Your message here.
:::

---

CSSをカスタマイズする

以下のCSSを編集することでサイト全体のCSSをカスタマイズできます。

/src/css/custom.css

本番環境用にビルドする

ターミナルで以下のコマンドを打ちます。

npm run build

これで、buildディレクトリが作成され、そこに本番環境用のファイルが生成されます。
このファイル一式をサーバーにアップすればサイトが表示されます。

ビルド時の注意

pagesやblogディレクトリを削除した場合で、このディレクトリへのリンクがdocs配下のページやdocusaurus.config.jsで指定されていると、ビルド時に「リンクが壊れている」とエラーが出てビルドに失敗しますので、ご注意ください。

エラーメッセージを確認すると、どのページへのリンクが壊れているのかが分かりますので、そこから該当のファイルを探してみてください。

ローカル環境でビルドファイルを確認する

以下のコマンドを実行すると、buildディレクトリのファイルをlocalhostで実行する事ができます。

npm run serve

デプロイする

Docusaurusは、GitHub PagesやNetlifyなどのホスティングサービスにデプロイする機能が用意されています。

詳しくは公式のドキュメントをご確認ください。

Deployment

デプロイ機能のサポート外のサーバーにアップロードする場合は、buildディレクトリのファイル一式をFTPなどでアップロードしてください。

詳細オプション : サイト内検索Algolia DocSearchを設置する

Docusaurusでは、Algolia DocSearchをサイト内検索として利用できます。

Algolia DocSearchは、サイト内をクロールして、インデックスを作成することでサイト内検索を可能にしてくれるサービスです。

そのため、利用するには、サイトが公開されている事が前提条件です。
アクセス制限をかける必要があるサイトでは利用できませんのでご注意ください。

実装に当たっては以下のドキュメントをご参考ください。
Search | Docusaurus

詳細オプション : サイトにnoindex, nofollowのメタタグを追加する

ドキュメントサイトを非公開にしたい場合、IPアドレスによる制限やBasic認証などを設定する必要がありますが、docusaurus.config.jsに以下のコードを追加することで、サイトにnoindex, nofollowのメタタグを追加できます。

noIndex: true,

これにより、各ページに以下のメタタグが挿入されます。

<meta name="robots" content="noindex, nofollow">

他にも色々カスタマイズ可能です。

本記事で紹介した他にも、色々な機能や用意されています。

以下に一例を掲載します。

• ドキュメントのバージョンを作成してプルダウンで選択可能にする
• Reactによるオリジナルのコンポーネントの作成
• インラインでTable of Contentを生成
• サイトのローカライズ機能

他にも色々出来る事はありそうですが、本記事の内容だけで、十分マニュアルサイトを作成することが可能です。

「デザインはシンプルで良いが、割とページのボリュームがあって、情報がきちんと整理されたマニュアルを短時間で作りたい」という要件にはぴったりのツールだと思います。

Docusaurusを使ってしまうと、もう、PowerPointやWordで何10ページものマニュアルを作る気にはなれません…。

サーバーにアップロードできない場合はPandocかStackEditを使いましょう

Docusaurusは非常に便利なツールなのですが、ウェブサーバーが必須になります。

buildディレクトリのファイル一式をローカルマシンで開いても正しく表示されません。 ローカル環境で表示させる場合も、ウェブサーバーを立ち上げる必要があります。

そのため、ローカル環境で気軽に閲覧したいという場合は、同じくマークダウンファイルを目次付きのHTMLに変換してくれるStackEditやPandocの利用をオススメします。

こちらに関しては、以下の記事で解説していますので、ご参考にしてみてください。

参考記事
Markdownを素敵なHTMLに変換するツール3選

---