Markdownをサイト化できる「Docusaurus」使ってみた

0. はじめに

Markdownでごりごりドキュメントや技術記事を書いている人達にとっては、
「あ、これ外部公開したいからいい感じにサイト化したい！」
っていうときが3年に1回くらいあるかと思います。
そんなときに便利な Docusaurus というのがあるようなので使ってみました。

• 「ドキュザラス」と読む(「ドックザウルス」かとおもた)
• Facebookが開発している
• オープンソースである

1. 環境構築

Node.jsがインストールされていることを前提とします。
参考：Node.jsを学ぶ中で必ず押さえておきたいこと

1-1. Docusaurusをインストールする

コマンドプロンプトにて任意のフォルダへ移動し、以下のコマンドを実行します。

npx create-docusaurus@latest <プロジェクトフォルダ名> <使用するテンプレート名>

<使用するテンプレート名>には、classic または facebook といったテンプレート名を指定します。特に理由がなければclassicでいいようですが、詳しくは公式で・・・

今回は以下のようにしてみました。

npx create-docusaurus@latest DocusaurusSample classic

コマンド実行が成功すると以下のようなフォルダ＆ファイルが作成されます。

1-2. 動作確認

以下のコマンドを実行します。

cd <プロジェクトフォルダ名>
npm start

http://localhost:3000/
にアクセスし、以下のようなサイトが表示されればOKです。

2. サイト作成前の準備

2-1. 不要なフォルダを削除する

今回は簡単なドキュメントサイトを構築します。
そのため、以下2つのフォルダは不要となるので削除します。

DocusaurusSample
┗ blog ・・・ 削除！
┗ src
  ┗ page ・・・ 削除！

フォルダを削除すると、ページが見つからなくなるため「Page Not Found」が表示されます。

2-2. 設定ファイルの変更

TOPとなるページを変更するため、docusaurus.config.jsファイルを以下のように変更します。

docusaurus.config.js

  presets: [
    [
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          // ----- ①以下の行を追加 -----
          routeBasePath: "/",
          sidebarPath: require.resolve('./sidebars.js'),
          // Please change this to your repo.
          // Remove this to remove the "edit this page" links.
          editUrl:
            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
        },
        // ----- ②以下は不要なため削除 -----
        //blog: {
        //  showReadingTime: true,
        //  // Please change this to your repo.
        //  // Remove this to remove the "edit this page" links.
        //  editUrl:
        //    'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
        //},
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      }),
    ],
  ],

3. サイトの作成

• TOPページ＆記事ページのMarkdownファイルを用意してください😇
  • TOPページのファイル名はindex.mdとします。
• 既存のtutorial-basics、tutorial-extrasフォルダは不要なため削除します。
  • これらはサンプルのMarkdownです。
  • 既存のintro.mdはそのままで。
• 以下の構造のようにMarkdownファイルを配置してください。
  • CSharpはFlutterフォルダです。
  • フォルダ構造にすることで、記事をグルーピングできます。

DocusaurusSample
┗ docs
  ┗ CSharp
    ┗ ANTLRを使って構文解析を行う.md
    ┗ ResXManagerを使用して多言語対応を行う.md
    ┗ ストップforeach！LINQで集合結合する.md
  ┗ Flutter
    ┗ 【Windows編】FlutterとCodemagicを使ってAndroidiOSアプリを生成するまで.md
    ┗ FlutterWeb + Firestoreを連携した超簡単なサンプルアプリを作成して自動デプロイする.md
  ┗ index.md
  ┗ intro.md

すると、以下のように自分で作成したMarkdownがサイト化されて表示されます😍

4. おわりに

• とても簡単にサイト構築ができました😊
• Markdownを増やすだけで、記事を増やせるので運用が手軽そうですね😊
• Markdownの記法によっては、一部エラーになる模様です😫
• docusaurus.config.jsに手を入れることで、ヘッダーやフッターのカスタマイズも手軽に行えます😊
• もうちょっといじってみて、全体のデザインを変更したりしてみたいと思います😊