Docusaurusを使って設計ドキュメント用の静的サイトをサクッと構築してみた
みなさんこんにちは！
i-Vinciで１番の暇人、藤田です。
実は弊社、技術的知見の共有を目的として、社内でTechLead活動という技術研究の活動を行っています。
具体的には、テーマを決めてチームを組んでアプリを作り、そこで得た知見をドキュメントなどにまとめて知識を共有する、という活動を行っています。
このテックブログの活動とは、一応別の活動ですが、ところどころいい感じに協力してるようなアレです。
会社から開発環境用の予算なども出してもらって、かなり自由にやらせてもらっています。
その活動の中で設計ドキュメントを取りまとめるサイトを作る必要が出て来ました。
Docusaurusというツールを使ってサクッと構築してみたので、今回はその紹介となります。
TechLead活動でのドキュメント管理
さて、みなさんのプロジェクトや案件では、どのような形でドキュメントを作成して、どのような方法で管理されておりますでしょうか？
弊社ではMS365を導入していて、普段はSharePointなどでドキュメントの共有を行っています。
......いえ、正確にはSharePointを使って「Excel」を共有しています。
しかしTechLead活動では、レビューのしやすさやドキュメントのバージョン管理などを考えて、設計書もしくはそれに準ずるメモをMarkdownで作成して、GitHubで管理することにしました。
設計ドキュメントを作成するにあたり、図などもいい感じに入れたくなります。
Markdownファイル上で図を表現する方法はいろいろありますが、今回は、GitHubのファイルビューワーで表示することができるMermaid記法で直接Markdownファイルに書くことにしました。
これもレビューのしやすさを考えてのことです。
これらの要件を満たすツールとして、Docusaurusを選びました。
これは完全に余談ですが、とにかくエンジニアという人種は、Excelで全てを解決・判断しがちです。
「あの日の議事録？このExcelファイルの"議事録_yyyyMMdd"シートにまとめました！」
「進捗の予実を管理したい？〇〇さんが作った神エクセルがあるから、それ使って！」
「データを集積・分析して、その結果をファイルに出力したい？それだったらエクセルで実現できますよ！」
「新人のプログラミングの素養を知りたい？VBAでなんか作らせてみればわかりますよ！」
私はエクセルとは、IT分野の傘のようなものだと考えています。
傘は、その機能的なデザインの完成度の高さゆえに、何百年も前からデザインにほとんど変化がないようです。
あまりにも完成されているが故に長い年月が過ぎても進化をしないのです。完成されているが故に強く、またそれ故に弱いと。
エクセルも似たような感じですよね〜。大体の仕事はエクセルで事足りてしまう感じのアレですが、ところどころ痒いところに手が届かない感じのそれです。
あと単純にGitで扱いづらいっすよね、Excel。
Docusaurusとは？
Docusaurusは、Single Page Applicationの静的サイトジェネレータです。
基本的にMarkdownファイルのみでページを作ることが出来るので、ドキュメント用のサイトなどをお手軽に構築することが出来ます。
また実装としてはReactを使っていて、Reactの知見がある方ならかなり自由にカスタマイズすることも可能です。
さらにJSXのMarkdown拡張であるMDXが、mdファイル、mdxファイルの両方で使えます。（MDX v1に対応）
とりあえず、触っていってみましょう。
前提
Docusaurusを動かすにはNode.jsのバージョン16.14以上がインストールされている必要があります。(参考)
また、本記事を執筆時点でDocusaurusのバージョンは、2.3.1でした。(2.3.0より以前のバージョンだと、Mermaid記法の導入は別の方法での導入が必要です。本記事では割愛)
プロジェクト作成
以下のコマンドを実行してもらうと、カレントディレクトリ直下に"my-website"ディレクトリが作成されます。
npx create-docusaurus@latest my-website classic
# or TypeScriptバージョンを立てたい人は以下
npx create-docusaurus@latest my-website classic --typescriptプロジェクトが作成されたら、以下のコマンドを実行すると、http://localhost:3000でドキュメントサイトが見れるようになります。
cd my-website
npm start
非常に簡単ですね。
Docsページの作成
現在、ページ上部のnavバーの部分に、"Tutorial", "Blog"の２つが表示されていると思います。
設計用のドキュメントサイトが必要なので、"Tutorial"を"Docs"に名前を変更し、"Blog"の項目を削除したいと思います。
Tutorial -> Docs
ルーティングなどを含めて設定の変更は、docusaurus.config.jsというファイルを編集したら大体できるようです。
configに定義されているthemeConfigの中身をいい感じに変更します。
introとかTutorialとなっている部分を適宜いい感じに変えてあげます。
また、docsディレクトリ配下の不要なディレクトリとファイルは削除しておきます。
Blogページの削除
こちらもdocusaurus.config.jsファイルをいい感じに編集します。
こんな感じです。
// @ts-check
// Note: type annotations allow type checking and IDEs autocompletion
const lightCodeTheme = require('prism-react-renderer/themes/github');
const darkCodeTheme = require('prism-react-renderer/themes/dracula');
/** @type {import('@docusaurus/types').Config} */
const config = {
title: 'My Site',
tagline: 'Dinosaurs are cool',
favicon: 'img/favicon.ico',
// Set the production url of your site here
url: 'https://your-docusaurus-test-site.com',
// Set the /<baseUrl>/ pathname under which your site is served
// For GitHub pages deployment, it is often '/<projectName>/'
baseUrl: '/',
// GitHub pages deployment config.
// If you aren't using GitHub pages, you don't need these.
organizationName: 'facebook', // Usually your GitHub org/user name.
projectName: 'docusaurus', // Usually your repo name.
onBrokenLinks: 'throw',
onBrokenMarkdownLinks: 'warn',
// Even if you don't use internalization, you can use this field to set useful
// metadata like html lang. For example, if your site is Chinese, you may want
// to replace "en" with "zh-Hans".
i18n: {
defaultLocale: 'en',
locales: ['en'],
},
presets: [
[
'classic',
/** @type {import('@docusaurus/preset-classic').Options} */
({
docs: {
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/',
},
theme: {
customCss: require.resolve('./src/css/custom.css'),
},
}),
],
],
themeConfig:
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
({
// Replace with your project's social card
image: 'img/docusaurus-social-card.jpg',
navbar: {
title: 'My Site',
logo: {
alt: 'My Site Logo',
src: 'img/logo.svg',
},
items: [
{
type: 'doc',
docId: 'index',
position: 'left',
label: 'Docs',
},
],
},
footer: {
style: 'dark',
links: [
{
title: 'Docs',
items: [
{
label: 'Docs',
to: '/docs/',
},
],
},
],
copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
},
prism: {
theme: lightCodeTheme,
darkTheme: darkCodeTheme,
},
}),
};
module.exports = config;ページ追加
docsディレクトリ配下にディレクトリやMarkdownファイルを新しく追加することで、ページが新しく追加されます。
いくつかいい感じに追加してみましょう。
私はこんな感じで追加してみました。
1ディレクトリ配下には何もファイルを置いていません。そのためブラウザ上には表示されません。
DBディレクトリ配下のDynamodb.mdとAurora.mdですが、実はDynamodb.mdの一行目に以下のような指定をしているため、Aurora.mdよりも上位に表示されています。
---
sidebar_position: 1
---また、docs直下にsample-img.pngを配置していますが、ブラウザ上には表示されません。
色々と決まり事があるようですが、このあたりに大体書いてあるようです。
Mermaid記法の導入
この辺りに導入の仕方が書いてあります。
以下のコマンドを実行して
npm install --save @docusaurus/theme-mermaid下記の内容をdocusaurus.config.jsのmodule.exports内に追記して
markdown: {
mermaid: true,
},
themes: ['@docusaurus/theme-mermaid'],再度npm startしてもらえると以下のような図をMermaid記法を使って作れるようになります。
設計書で通常使うような図だとMermaid記法だけで足りるのではないでしょうか？
まとめ
Docusaurusを使えば色々といい感じにドキュメントサイトがサクッと出来ました。