Docusaurusをドキュメントのみのサイトとして構築する

先日試してみたDocusaurusをドキュメントのみのサイトとして構成する方法を試してみました。
2020.03.26

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

先日Docusaurusを導入して試してみました。

Facebook製のドキュメント生成ツール Docusaurusを試してみた

標準でドキュメントとブログを管理できる構成で作成されていました。今回はデフォルトの構成からブログ機能を外し、ドキュメントのみのサイトを構築する方法を試してみました。

環境

次の環境で検証をしています。

$ sw_vers
ProductName:	Mac OS X
ProductVersion:	10.15.4
BuildVersion:	19E266

$ node -v
v10.19.0

$ grep @docusaurus package.json
    "@docusaurus/core": "^2.0.0-alpha.48",
    "@docusaurus/preset-classic": "^2.0.0-alpha.48",

プロジェクトの作成

作成は前回と同様、コマンドでさくっと済ませます。

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

設定変更で構成を変えてみる

実現したい構成(挙動)は次のものです。

  • サイトのヘッダからメニューを削除
    • ドキュメントのみのサイトなので不要
  • ドキュメントのURLから/docs/を削除
    • http://localhost:3000/doc1というURLでアクセスしたい
  • サイトのトップページにアクセスした際、自動的にドキュメントのトップに遷移できる

それぞれ順番に見ていきましょう。

サイトのヘッダからメニューを削除

これは前回も似たようなことをやりました。今回はヘッダメニューをまるっと消してしまいます。

docusaurus.config.js

@@ -13,20 +13,6 @@ module.exports = {
         alt: 'My Site Logo',
         src: 'img/logo.svg',
       },
-      links: [
-        {
-          to: 'docs/doc1',
-          activeBasePath: 'docs',
-          label: 'Docs',
-          position: 'left',
-        },
-        {to: 'blog', label: 'Blog', position: 'left'},
-        {
-          href: 'https://github.com/facebook/docusaurus',
-          label: 'GitHub',
-          position: 'right',
-        },
-      ],
     },
     footer: {
       style: 'dark',

ドキュメントのURLから/docs/を削除

デフォルトでは、ドキュメントにはhttp://localhost:3000/docs/doc1のように/docs/のパスが付きます。ドキュメントのみのサイトにする場合は冗長に感じられるためhttp://localhost:3000/doc1でアクセスできるようにします。これはrouteBasePathの設定を追加するだけです。

docusaurus.config.js

@@ -83,6 +69,7 @@ module.exports = {
       '@docusaurus/preset-classic',
       {
         docs: {
+          routeBasePath: '',
           sidebarPath: require.resolve('./sidebars.js'),
           editUrl:
             'https://github.com/facebook/docusaurus/edit/master/website/',

サイトのトップページにアクセスした際、自動的にドキュメントのトップに遷移できる

ドキュメントのみのサイトにする場合、デフォルトのトップページは不要です。そのためアクセスされたらドキュメントのトップに遷移するようにリダイレクトをしかけましょう。src/pages/index.jsを次のようなシンプルな内容に置き換えます。

src/pages/index.js

import React from 'react';
import { Redirect } from '@docusaurus/router';
import useBaseUrl from '@docusaurus/useBaseUrl';

function Home() {
  return <Redirect to={useBaseUrl('doc1')} />;
}

export default Home;

動作確認

それでは最後に動作確認をしておきます。コマンドでサイトを起動しましょう。

$ npm start

自動的にドキュメントトップにリダイレクトされ、実現したかった構成ができています!

まとめ

Docusaurusのデフォルト構成からドキュメントのみの構成に変更してみました。不要なファイルなどを整理すればすぐにでも使い始められますね。