この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。
こんにちは。サービスグループの武田です。
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コンポーネントとして作られているため、カスタマイズには多少知識が求められるでしょうか（消すだけであればさくっとできますね）。
src/pages/index.js
@@ -61,22 +61,6 @@ function Home() {
<Layout
title={`Hello from ${siteConfig.title}`}
description="Description will go into a meta tag in <head />">
- <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でされているため、このファイルを修正します。
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で定義されているため、このファイルを修正します。
sidebar.js
@@ -1,6 +1,6 @@
module.exports = {
someSidebar: {
- Docusaurus: ['doc1', 'doc2', 'doc3'],
Features: ['mdx'],
+ Docusaurus: ['doc1', 'doc2', 'doc3'],
},
};
修正は定義する順番を変えるだけの簡単なものです。自動反映だとナビゲーションがおかしくなってたので物理リロードしました。メニューの順番が入れ替わっています。
まとめ
まずは使ってみようということで、インストールから簡単な変更を試してみました。導入も簡単ですので、ドキュメント生成ツールをお探しの方はぜひ一度試してみてください。
25
