ドキュメント作成ツール『Docusaurus』のチュートリアルを試してみた

2020.07.30

プロジェクトのドキュメントを構築する上で、個人的にはここまでMkDocsというツールを使って来ていましたが、以前投稿されていた下記のツール『Docusaurus』なるものを見て『これも良さそうだな...』と思い、公式ドキュメントにてチュートリアルが用意されていたので試してみました。当エントリはその『チュートリアル』を試してみた内容を紹介しています。

目次

 

事前準備

事前準備として、git及びnode、yarnがインストールされている事が条件となります。yarnはオプション扱いではありますが、チュートリアルの内容曰く「強く推奨します」とのことでしたのでここではそれに乗る形で進めたいと思います。

% git --version
git version 2.26.2
# Nodeはv8以上が条件.
% node -v
v13.13.0
% brew install yarn
% yarn -v
1.22.4

 

初期セットアップ

プロジェクト名を指定する形でyarn global add (プロジェクト名)とコマンド実行することで、Docusaurusプロジェクトとして認識されるようになります。

% yarn global add docusaurus-init
yarn global v1.22.4
[1/4] 🔍  Resolving packages...
[2/4] 🚚  Fetching packages...
[3/4] 🔗  Linking dependencies...
[4/4] 🔨  Building fresh packages...
success Installed "docusaurus-init@1.14.1" with binaries:
      - docusaurus-init
✨  Done in 6.25s.
%

 

サイト作成

docusaurus-initコマンドを実行すると必要なファイル群が作成されます。

% mkdir docusaurus-tutorial 
% cd docusaurus-tutorial 
% docusaurus-init
Website folder created!

Installing latest version of Docusaurus in website.

yarn add v1.22.4
warning package.json: No license field
info No lockfile found.
warning No license field
[1/4] Resolving packages...
:
:
[2/4] Fetching packages...
[3/4] Linking dependencies...
[4/4] Building fresh packages...
success Saved lockfile.
warning No license field
success Saved 639 new dependencies.
info Direct dependencies
└─ docusaurus@1.14.4
info All dependencies
├─ @babel/core@7.10.5
:
:
    │       ├── undraw_tweetstorm.svg
    │       └── undraw_youtube_tutorial.svg
    └── yarn.lock
Done in 0.59s.
%

 

ローカルサーバ起動&停止

作成したプロジェクト配下に出来ているwebsiteフォルダに移動し、yarn startコマンド実行でサーバが起動。

% ls
Dockerfile		docker-compose.yml	docs			website
% cd website
% ll
total 592
drwxr-xr-x    4 xxxxxxxxxx  staff     128  7 24 22:22 static
-rw-r--r--    1 xxxxxxxxxx  staff    3205  7 24 22:22 siteConfig.js
-rw-r--r--    1 xxxxxxxxxx  staff     174  7 24 22:22 sidebars.json
-rw-r--r--    1 xxxxxxxxxx  staff    4072  7 24 22:22 README.md
drwxr-xr-x    3 xxxxxxxxxx  staff      96  7 24 22:22 pages
drwxr-xr-x    3 xxxxxxxxxx  staff      96  7 24 22:22 core
drwxr-xr-x    7 xxxxxxxxxx  staff     224  7 24 22:22 blog
-rw-r--r--    1 xxxxxxxxxx  staff     376  7 24 22:22 package.json
-rw-r--r--    1 xxxxxxxxxx  staff  283975  7 24 22:22 yarn.lock
drwxr-xr-x  700 xxxxxxxxxx  staff   22400  7 24 22:22 node_modules

% yarn start
yarn run v1.22.4
warning package.json: No license field
$ docusaurus-start
LiveReload server started on port 35729
Docusaurus server started on port 3000

http://localhost:3000/の形でブラウザが立ち上がり、ドキュメントサイトとして表示されました。

 

新規ページ作成(非ドキュメントページ)

Docusaurusでは2種類のページを作成することが出来ます。1つ目は「通常のページ」。ドキュメントページとは異なり、ドキュメント内容をサポートする立ち位置のコンテンツページを作成する際に使えます。

こちらのページはJavascriptを用いて作成します。ここではhello-world.jsというファイル名を作成し、

% pwd
/Users/xxxxxxxxxx/xxxxxx/project/docusaurus-tutorial/website
% touch pages/en/hello-world.js
% vi pages/en/hello-world.js 

以下の内容で中身を記述。

hello-world.js

const React = require('react');

const CompLibrary = require('../../core/CompLibrary.js');

const Container = CompLibrary.Container;
const GridBlock = CompLibrary.GridBlock;

function HelloWorld(props) {
  return (
    <div className="docMainWrapper wrapper">
      <Container className="mainContainer documentContainer postContainer">
        <h1>Hello World!</h1>
        <p>This is my first page!</p>
      </Container>
    </div>
  );
}

module.exports = HelloWorld;

http://localhost:3000/hello-worldにアクセス。以下の様にページが表示されました。

 

ページの修正→即変更が反映

Reactは、静的マークアップをレンダリングするためのテンプレートエンジンとして使用されています。Reactの表現力を活用して、リッチなWebコンテンツを構築できます。ページの作成について詳しくは、こちらをご覧ください。

 

ページの作成(ドキュメントページの作成)

基本的に必要になりそうなのはこちらのページ。docフォルダ配下に作成することでドキュメントページとして機能します。docフォルダ配下にmdファイル(doc9.md)を作成。

% pwd
/Users/xxxxxxxxxxxx/xxxxxxxxx/project
% cd docusaurus-tutorial 
% ll
total 16
drwxr-xr-x  13 xxxxxxxxxx  staff  416  7 24 22:23 website
-rw-r--r--   1 xxxxxxxxxx  staff  497  7 24 22:22 docker-compose.yml
-rw-r--r--   1 xxxxxxxxxx  staff  145  7 24 22:22 Dockerfile
drwxr-xr-x   7 xxxxxxxxxx  staff  224  7 24 22:22 docs
% cd docs 
% touch doc9.md
% vi doc9.md 

ファイルの中身は以下のように記述します。

---
id: doc9
title: This is Doc 9
---

I can write content using [GitHub-flavored Markdown syntax](https://github.github.com/gfm/).

## Markdown Syntax

**Bold** _italic_ `code` [Links](#url)

> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
> id sem consectetuer libero luctus adipiscing.

* Hey
* Ho
* Let's Go

ドキュメントページに関しては、sidebars.jsonに指定を行う必要があるようです。表示順番を指定します。website/sidebars.jsonを開き、"doc1 "の後に "doc9 "を追加します。IDに関してはMarkdownファイルのメタデータと同じものでなければなりません。

% cd ..
% vi website/sidebars.json

website/sidebars.json

{
  "docs": {
    "Docusaurus": [
      "doc1",
      "doc9"
    ],
    "First Category": ["doc2"],
    "Second Category": ["doc3"]
  },
  "docs-other": {
    "First Category": ["doc4", "doc5"]
  }
}

サイトバーを変えたのでサーバを一旦リスタートがさせ、ページ遷移で内容を確認。新しく追加した内容が確認出来ました!その他ページ作成に関しては下記を参照。

 

サイトのパブリッシュ(Publish the Site)

Docusaurusでは、作成したコンテンツを静的コンテンツとして出力することが出来ます。パブリッシュされるコンテンツについては、website/siteConfig.jsで設定を行います。

% pwd
/Users/xxxxxxxxxxx/xxxxxxxx/docusaurus-tutorial/website
% vi siteConfig.js 

今回は最低限必要なプロジェクト名の設定などを行いました。

const siteConfig = {
  title: 'Test Site', // Title for your website.
  tagline: 'A website for testing',
  url: 'https://your-docusaurus-test-site.com', // Your website URL
  baseUrl: '/docusaurus-tutorial/', // Base URL for your project */
  // For github.io type URLs, you would set the url and baseUrl like:
  //   url: 'https://facebook.github.io',
  //   baseUrl: '/test-site/',

  // Used for publishing and more
  projectName: 'docusaurus-tutorial',
  organizationName: 'Classmethod, Inc.',
  // For top-level user or org sites, the organization is still the same.
  // e.g., for the https://JoelMarcey.github.io site, it would be set like...
  //   organizationName: 'JoelMarcey'

websiteフォルダでyarn buildコマンドを実行。buildフォルダにコンテンツが出来るのでそれを任意のWebサイト・サービスにホストすればOKです。

% pwd
/Users/xxxxxxxxxx/xxxxxxxx/project/docusaurus-tutorial/website
% yarn build
yarn run v1.22.4
warning package.json: No license field
$ docusaurus-build
generate.js triggered...
feed.js triggered...
feed.js triggered...
sitemap.js triggered...
Site built successfully. Generated files in 'build' folder.
✨  Done in 7.16s.
%

 

まとめ

という訳で、静的ドキュメント作成ツールDocusaurusのチュートリアルを試してみた内容の紹介でした。

こちらの内容に関しても、まだほんの触りの部分を触った程度。MkDocs同様、実践内容を想定したユースケースで色々「何が出来るか、どういう風に出来るのか」を試していきたいと思います。