ドキュメント作成ツール『Docusaurus』のチュートリアルを試してみた
プロジェクトのドキュメントを構築する上で、個人的にはここまで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 "[email protected]" 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 └─ [email protected] info All dependencies ├─ @babel/[email protected] : : │ ├── 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
以下の内容で中身を記述。
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
{
"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同様、実践内容を想定したユースケースで色々「何が出来るか、どういう風に出来るのか」を試していきたいと思います。
