Facebook製のドキュメント生成ツール Docusaurusを試してみた | DevelopersIO (original) (raw)

こんにちは。サービスグループの武田です。

Markdownで記述できるドキュメント生成ツールを探していたところDocusaurusというツールを知りました。簡単ですが導入して試してみましたので紹介します。

Docusaurusとは

DocusaurusはFacebook製のドキュメント生成ツールで、主にOSSのマニュアルやお知らせなどのブログを管理するために使われているようです。次のような特徴があります。

MarkdownおよびJSXを含んだMDXでコンテンツを作成する
生成したドキュメント（サイト）はReactで動作し、カスタマイズも容易
多言語対応（ローカライズ）も可能
ドキュメントのバージョニングが可能で、プロダクトのバージョンに合わせたドキュメントを提供できる
Algoliaと連携させることで容易に検索機能を追加できる

なお執筆時点の安定版は1.14.xとなっていますが、せっかくなのでv2を試してみました。v2はalpha releaseとなっているため、本番運用する際には考慮が必要です。

環境

次のような環境で検証しています。

$ sw_vers ProductName: Mac OS X ProductVersion: 10.15.3 BuildVersion: 19D76

$ node -v v10.19.0

プロジェクトの作成

Docusaurus用のプロジェクト作成にはScaffoldコマンドが提供されているため、これを利用するのが簡単です。コマンドは次の形式で実行します。

$ npx @docusaurus/init@next init [siteName] [template] [rootDir]

templateにはclassicかfacebookが選べます。基本的にはclassicで大丈夫で、facebookを選ぶとFacebook open source project用のロゴが設定してあったりしました。

それでは実際に実行してみます。

$ cd /path/to/working $ npx @docusaurus/init@next init devio classic $ cd devio

作成されたファイルを確認してみます。パッケージマネージャーはnpmを使用しています。yarnがインストールされている環境の場合、自動的にyarnでパッケージの管理をします。

$ tree -I node_modules . ├── README.md ├── blog │ ├── 2019-05-28-hola.md │ ├── 2019-05-29-hello-world.md │ └── 2019-05-30-welcome.md ├── docs │ ├── doc1.md │ ├── doc2.md │ ├── doc3.md │ └── mdx.md ├── docusaurus.config.js ├── package-lock.json ├── package.json ├── sidebars.js ├── src │ ├── css │ │ └── custom.css │ └── pages │ ├── index.js │ └── styles.module.css └── static └── img ├── favicon.ico ├── logo.svg ├── undraw_docusaurus_mountain.svg ├── undraw_docusaurus_react.svg └── undraw_docusaurus_tree.svg

7 directories, 20 files

blog/
- ブログ用のMarkdownファイルを管理するディレクトリ
docs/
- ドキュメント用のMarkdownファイルを管理するディレクトリ
src/
- ドキュメントファイルではないページやカスタムReactコンポーネントを管理するディレクトリ
src/pages/
- Webページに変換されるコンテンツ
static/
- 静的ファイルを管理するディレクトリ
docusaurus.config.js
- サイトの設定ファイル
sidebar.js
- ドキュメントの構成を定義するファイル

ドキュメント用途ということであれば、docs/、docusaurus.config.js、sidebar.jsあたりが主に触っていくファイルということになります。

ブラウザで確認しながらカスタマイズしてみる

プロジェクトが作成できたらすぐにでもサイトを立ち上げて確認できます。次のコマンドを実行すると自動的にブラウザも開きます。なお、ファイルを変更すると自動的にブラウザがリロードされるため、修正箇所の確認も簡単です。

$ npm start

トップページを変えてみる

トップページのヘッダ部分を消してみます。src/pages/index.jsが該当ファイルです。Reactコンポーネントとして作られているため、カスタマイズには多少知識が求められるでしょうか（消すだけであればさくっとできますね）。

@@ -61,22 +61,6 @@ function Home() { <Layout title={Hello from ${siteConfig.title}} description="Description will go into a meta tag in ">

 <header className={classnames('hero hero--primary', styles.heroBanner)}>

```
   <div className="container">
```

     <h1 className="hero__title">{siteConfig.title}</h1>

     <p className="hero__subtitle">{siteConfig.tagline}</p>

```
     <div className={styles.buttons}>
```
```
       <Link
```
```
         className={classnames(
```

           'button button--outline button--secondary button--lg',

```
           styles.getStarted,
```
```
         )}
```
```
         to={useBaseUrl('docs/doc1')}>
```
```
         Get Started
```
```
       </Link>
```
```
     </div>
```
```
   </div>
```

 </header>
 <main>
   {features && features.length && (
     <section className={styles.features}>

消えました！

サイトのヘッダからBlogへのリンクを消してみる

続いてサイトのヘッダに設置されているブログへのリンクを消してみます。ヘッダは個別ページではなくテーマで扱っている部分です。テーマの設定はdocusaurus.config.jsでされているため、このファイルを修正します。

@@ -20,7 +20,6 @@ module.exports = { label: 'Docs', position: 'left', },

   {to: 'blog', label: 'Blog', position: 'left'},
   {
     href: 'https://github.com/facebook/docusaurus',
     label: 'GitHub',

themeConfig.navbar.links[]からBlogへのナビゲーションを消しただけです。きれいに消えましたね。

ドキュメントの順番を変えてみる

最後にドキュメントのコンテンツの順番を変えてみます。デフォルトでは大枠でDocusaurus、Featuresの順番で、これを逆にしてみます。ドキュメントの構成はsidebar.jsで定義されているため、このファイルを修正します。

修正は定義する順番を変えるだけの簡単なものです。自動反映だとナビゲーションがおかしくなってたので物理リロードしました。メニューの順番が入れ替わっています。

まとめ

まずは使ってみようということで、インストールから簡単な変更を試してみました。導入も簡単ですので、ドキュメント生成ツールをお探しの方はぜひ一度試してみてください。