多くの開発者が、軽量なウェブサイトやアプリケーション、その他の小規模なプロジェクトで、WordPressやその他コンテンツ管理システム（CMS）に代わる選択肢として、静的サイトジェネレータを利用しています。静的サイトは、一般的に高速であり高い安全性を誇ります。結果的に保守に手間のかからないサイトやアプリケーションを構築できます。
Docusaurusはそのような静的サイトを作るのに便利なジェネレータの1つであり、開発コミュニティで急速に人気を集めています。
この記事では、静的サイトジェネレータであるDocusaursを使用するメリット、開発者の間での人気の高まり、そしてKinstaでのデプロイ方法をご紹介します。
Docusaurusとは
Docusaurusは、トップクラスのJavaScriptライブラリの1つであるReactをページ作成のUIライブラリとして使用する、人気の静的サイトジェネレータです。他のジェネレータと同様、セットアップや変更が簡単で、最も重要な点として、静的ウェブサイトを立ち上げるために必要なものがすべて揃っています。
Docusaurusは、コンテンツそのものに特化したウェブサイトの作成・管理に向いています。ブログ機能を搭載したウェブサイトをすばやく簡単に構築し、コンテンツを公開するのにうってつけです。
Docusaurusではコンテンツが重視されるため、Wikiのようなドキュメントサイトの作成に最適です。また、マークダウンを使用しているため、コラボレーションやgitリポジトリでの保存とも高い互換性を誇ります。さらに、国際化、検索、豊富なテーマなどの素晴らしい機能がずらり。
Docusaurusの特徴は以下の通りです。
- Reactを使用して構築
- MDX v1をサポート
- マークダウンによるReactコンポーネントの埋め込みに対応
- ドキュメントのバージョン管理
- Git、Crowdin、その他の翻訳ツールとの互換性により、ドキュメントの翻訳、一括または個別のデプロイメントが可能
Docusaurusの利用者
DocusaurusはFacebookによって開発されました。多くの大企業がこれを利用しているのは、何も不思議なことではありません。
現在Docusaurusを使用している顕著な例を挙げると、以下の通りです。
人気は上昇中で、今後もさらなる採用が予想されます。
Docusaurusのインストール方法
Docusaurusのインストールは非常に簡単で、ものの数分もあれば完了します。今回の記事では、ブログセクション付きのドキュメントサイトを構築し、外観をカスタマイズしていきます。
1時間もかからずに、立ち上げまでこぎつけることができます。
それでは、始めましょう。
必要なもの
Docusarus は、Node.js 16.14 以降が必要です。フラットファイルSSGなので、追加のデータベースは必要ありません。
Node.js 16.14以上をお持ちでない場合は、Node.js をインストールするか、現在のバージョンをアップグレードすることから始めてください。その後、以下のDocusaurusのインストール手順に進みます。
また、こちらのGitHubリポジトリにあるサンプルDocusaurusサイトを使用する予定です。このサンプルサイトまたはDocusaurusを一からインストールすることができます。
インストール手順
Docusaurusをインストールするには次のコマンドを実行します。
npx create-docusaurus@latest classicこれにより、プロジェクトのフォルダが作成され、その中にクラシックテーマが組み込まれます。クラシックテーマには、ブログ、ページ、CSSフレームワークなど、複数の機能が標準で搭載されています。
インストール後、次のコマンドでローカルサーバーを起動します。
npm startデプロイ用に最適化したバージョンを構築するには、代わりに以下のコマンドを実行します。
npm run build構造
Docusaurusインスタンスをインストールしたら、プロジェクトディレクトリを開いて新しいサイトの「骨組み」を見てみましょう。
ファイル構造はこのようになっています。
my-website
├── blog
│ ├── 2019-05-28-hola.md
│ └── 2020-05-30-welcome.md
├── docs
│ ├── doc1.md
│ └── mdx.md
├── src
│ ├── css
│ │ └── custom.css
│ └── pages
│ ├── styles.module.css
│ └── index.js
├── static
│ └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lockこれらのファイルやフォルダについての大事な点は以下の通りです。
/blog：ブログに関連するすべてのファイルが含まれています。/docs：ドキュメントに関連するすべてのファイルが含まれています。sidebar.jsファイルで並び順を変更できます。/src：ページやカスタムコンポーネントのような、ドキュメント以外のすべてのファイルが格納されます。/src/pages：すべてのJSX/TSX/MDXファイルが、ページに変換されます。/static：最終的なビルドフォルダにコピーされる静的ファイルです。docusaurus.config.js：Docusaurusの設定ファイルです。packaged.json：DocusaurusサイトはReactアプリなので、ここにReactの依存関係や使用するスクリプトがすべて含まれます。sidebar.js：サイドバーのドキュメントの並び順を指定できます。
Docusaurusをカスタマイズする
シンプルなファイル構造からお分かりのように、Docusaurusは使いやすく、ナビゲーションも簡単です。ファイルは、お好みのテキストエディターやIDEで開いて編集することができます。
それでは、すぐに調整できる項目から見てみましょう。
ホームページ
まず最初に、デフォルトのホームページの調整についてです。例えば、自分身のプロジェクトを掲載するなど、様々な手の加え方が考えられます。実際、Docusaurusのホームページは簡単に調整できます。
src/pages/index.jsファイルを開き、その中身に手を加えます。典型的なReactページなので、コンテンツを変更したり、好みのReactコンポーネントを作成したりすることで、自分好みに変えることができます。
設定ファイル
次に、重要なdocusaurus.config.jsファイルについてです。今回の説明に合うように情報を変更します。
名前と説明
設定ファイルの中に、以下のものがあります。
const config = {
title: 'My Site',
tagline: 'Dinosaurs are cool',
url: 'https://your-docusaurus-site.com',
baseUrl: '/',サイトの中身にあわせてサイト名とその説明を変更し、ファイルを保存してください。
ナビゲーションバー
ナビゲーションバーを編集するには、navbarの項目を探します。
この例では、Kinstaのリンクを配し「Tutorial」アイテムの名前を「Starter documentation」に変更し、Kinstaのロゴを追加しています。
コードは以下の通りです。
navbar: {
title: 'Kinsta starters',
logo: {
alt: 'Kinsta Logo',
src: 'img/kinsta-logo-alpha-purple.png',
},
items: [
{
label: 'Kinsta starters',
to: '/docs/intro',
},
{to: '/blog', label: 'Blog', position: 'left'},
{
href: 'https://github.com/kinsta',
label: 'GitHub',
position: 'right',
},
],
},フッター
Docusaurusにおけるフッターは、コンテンツとリンクの2つのセクションから構成されています。
フッターコンテンツ
フッターコンテンツの大部分（リンクのリストを除く）はthemeConfig.footerファイルに記述することができます。ここでロゴと著作権についての表示を扱うのが得策です。
今回の例では、以下のようにフッターの設定を変更しました。
module.exports = {
themeConfig: {
footer: {
logo: {
alt: 'Kinsta Logo',
src: 'img/kinsta-logo.png',
href: 'https://kinsta.com',
width: 160,
height: 51,
},
copyright: `Copyright © ${new Date().getFullYear()} Kinsta. Built with Docusaurus.`,
},
},
};フッターリンク
フッターリンクの変更は、画面上部のナビゲーションバーを調整するのに似ています。docusaurus.config.jsのfooterセクションを探し、好みに合うように編集してください。
以下は、footerセクションの変更結果です。
footer: {
style: 'dark',
links: [
{
title: 'Docs',
items: [
{
label: 'Kinsta starters',
to: '/docs/intro',
},
],
},
{
title: 'Talk with us',
items: [
{
label: 'Discord',
href: 'https://discord.gg/vjRPMhFaBA',
},
{
label: 'Support',
href: 'https://kinsta.com/kinsta-support/',
},
{
label: 'Twitter',
href: 'https://twitter.com/kinsta',
},
],
},
{
title: 'More',
items: [
{
label: 'Application Hosting',
href: 'https://kinsta.com/application-hosting/',
},
{
label: 'Database Hosting',
href: 'https://kinsta.com/database-hosting/',
},
{
label: 'WordPress Hosting',
href: 'https://kinsta.com/wordpress-hosting/',
},
{
label: 'DevKinsta',
href: 'https://kinsta.com/devkinsta/',
},
],
},
],
};配色とCSS
Docusaurusのスタイリングプリセットには、Infimaが使用されています。これを考慮し、Docusaurusの作成者により、色やその他のCSS要素および宣言を変更する際に便利なウェブツールが公開されています。
ページ上で好みを選択すると、瞬時にcustom.cssファイル（色調を補完する美しい一連のファイル）が生成されます。このようにしてできあがったCSSファイルを、プロジェクトの/src/cssディレクトリにコピーして、参照することができます。
ドキュメント
ウェブサイトのすべてのドキュメントが、/docsフォルダに保存されます。もちろん、このフォルダ名はdocusaurus.config.jsで変更することができます。
テキストまたはHTMLエディターでマークダウン形式のファイルを作成し、そのフォルダにドロップするだけでOKです。各ファイルは次のようなものになります。
---
id: the-id
title: Title
---
# Rest of the documentIDに基づいて、Docusaurusにより、そのサブフォルダ内にある記事のURLが構築されます。yourdomain.com/docs/{id}
ドキュメントを複数のセクションに分割するには、サブフォルダを作成することもできます。ただし、サブディレクトリを機能させるためには、少し追加の作業が必要になります。
例えば、「Starters」という名前のドキュメントフォルダを作成したとします。サイトを再読み込みすると、サイドバーに自動で「Starters」リンクが表示されます。しかし、それをクリックすると、エラーが発生します。なぜなら、新しいフォルダにはまだインデックスページが存在しないからです。
この問題を解決する一番簡単な方法が、_category_.jsonファイルの作成です。これにより、フォルダに格納されているすべてのページのインデックスを生成することができます。コードは以下だけでOKです。
{
"label": "Starters",
"position": 2,
"link": {
"type": "generated-index",
"description": "All Kinsta Starters"
},
};これで、サイドバーが実際のファイル構造を反映したものになります。というのも、sidebar.jsファイルにはtutorialSidebar、[{type: 'autogenerated', dirName: '.'}],が含まれます。
自分自身で処理するには、次のようなものに変更できます。
tutorialSidebar: [
'intro',
'hello',
{
type: 'category',
label: 'Tutorial',
items: ['tutorial-basics/create-a-document'],
},
],ブログ
Docusaurusには洗練されたブログモジュールが組み込まれています。メインウェブサイトとあわせてブログを運営することで、プロジェクトで発生した変更を利用者に知らせたり、変更履歴としてプロジェクトのメモを残したりするのに効果的です。
各記事はこのようなメタ情報から構成されます。
---
slug: docusaurus-starter
title: Docusaurus Starter
authors: palmiak
tags: [starters, docusaurus]
---そしてもちろん、コンテンツそのものもあります。また、便利な<!--truncate-->タグがあり、投稿一覧に表示される要約の文字数を制限することができます。
加えて、各スタッフやメンバーのデータ整理に便利なauthors.ymlファイルを作成することもできます。例えば、次の通りです。
palmiak:
name: Maciek Palmowski
title: DevRel
url: https://github.com/palmiak
image_url: https://github.com/palmiak.pngこのファイルを用意することで、すべての作者のデータを一箇所に集め、簡単に参照できるようになります。
KinstaでDocusaurusサイトをデプロイする方法
WordPressサイト、スタンドアロンアプリケーション、データベースに加えて、Kinstaでは静的サイトを運営することができます。
コントロールパネル「MyKinsta」から直接、Docusaurusサイト、およびその他あらゆるウェブプロジェクトを管理可能です。
アプリケーションのデプロイ後には、アプリケーションの継続的な分析データをリアルタイムと履歴の両方から確認できます。
- 帯域幅の使用状況
- ビルド時間
- ランタイム
- CPU使用率
- メモリ使用量
MyKinstaを使ったデプロイメントはものの数分で完了します。
さっそく始めてみましょう。
前提条件─Docusaurusプロジェクトの設定
KinstaのアプリケーションホスティングプラットフォームでDocusaurusプロジェクトをホストするには、次のものが必要になります。
- package.jsonファイルに名前フィールドを用意する（これは何でもよく、デプロイメントに影響しません）
- package.jsonファイルにビルドスクリプトを記述する（Docusaurusプロジェクトにすでに含まれているはずです）
- npmのserveパッケージをインストールし、startスクリプトで serve-buildを指定する
これらの項目を終えたら、実際にサイトのデプロイに移ります。
Docusaurusプロジェクトをデプロイする
以下の簡単な手順でGitHubアカウントに接続し、Docusaurusサイトを起動します。
- MyKinstaアカウントにログインし、左側のメニューから「アプリケーション」タブに移動します。
- 青い「サービスを追加」ボタンを押し、ドロップダウンメニューから「アプリケーション」を選択します。
MyKinstaの「アプリケーション」タブで、青い「サービスを追加する」ボタンをクリックした後（「アプリケーション」にマウスを置いた状態） - MyKinstaからGitHubアカウントにまだ接続していない場合は、接続を促すポップアップが表示されます。「GitHubを使って続行」ボタンをクリックして次に進みます。
GitHubとの連携についての表示（ここでGitHubと接続し、既存のリポジトリをインポート─右下には白い「キャンセル」ボタンと青い「GitHubを使って続行」ボタンがある） - 新しいウィンドウが開き、Kinstaによるお客様のGitHubリソースへのアクセスと管理を許可するように求められます。GitHubアカウントにサインインしていることを確認した上で、下部にある緑色の「Authorize Kinsta」ボタンをクリックしてください。
GitHubから「Kinsta by Kinsta would like permission to:…」という認証ポップアップが表示される（「Cancel」、「Authorize」ボタン等） - 次の段階として、GitHub統合ウィザードに移行します。サイトデプロイ前の最後のステップです。表示されたフィールドを慎重に検討し、GitHubの構成とプロジェクトの要件に従って記入してください。リポジトリにDockerfileがあれば、これを使用してコンテナイメージをセットアップできます。そうでない場合は、Kinstaにより自動でコンテナイメージがセットアップされます。これがKinstaを通した最初のデプロイメントである場合には、先に進む前にGitHubのパーミッション編集が必要になることがあります。
MyKinstaのアプリケーションウィザード（「GitHubリポジトリ」フィールドの「GitHubの権限を編集」） Kinstaにすべてのリポジトリへのアクセスを許可するか、特定のリポジトリのみにアクセスを許可するかを選択できます。これについては、GitHubアカウントのアプリケーション設定からいつでも調整することができます。
GitHubの「Permissions」画面（「Repository access」には「All repositories」と「Only select repositories」の2つが表示されている） - 選択と確認が終わると、デプロイの詳細が表示されます。「設定を変更」や「再デプロイ」といった操作も実行可能です。
MyKinsta の「デプロイメントの詳細」ページ（デプロイしたブランチ名、コミット番号、付随するコミットメッセージ、デプロイ時間、選択したデータセンターの場所など） また、デプロイ中に発生したエラーとその原因も表示されるので、これを参考にして、簡単に対処することができます。問題の解決に苦戦した場合には、Kinstaのドキュメントにある、ロールアウトエラーに関する説明をご覧ください。
「ビルドプロセス失敗」というタイトルと「不明なビルドエラーが発生しました。」というメッセージ
エラーなしで（またはエラーを解決し）ここまで到達したら、おめでとうございます。Kinstaを通したDocusaurusサイトのデプロイに成功しました。ウィザードでの設定を完了すると、すぐにアプリケーション（静的サイト）が利用可能になります。アプリケーションのURLは、 https://your-docusaurus-site.kinsta.appのようなものになります。
Kinsta上のサンプルサイトを見てみましょう。
まとめ
驚くほど強力な機能、親しみやすいデザイン、直感的なナビゲーション、コンテンツ重視の構造など、Docusaurusは、合理的かつ整理された静的ドキュメントサイトやブログを簡単に展開・維持したい開発者に愛用されている優れたツールです。
価値あるコンテンツを用意したら、続いては、追加の機能について検討するフェーズです。Docusaurusで構築したサイトでは、検索エンジン最適化が重要な意味を持ちます。SEOランキングを上げるテクニックの数々も公開していますので、あわせてご覧ください。
Docusaurusを使ってサイトを構築したことはありますか？あなたのプロジェクトや経験について、以下のコメント欄でお聞かせください。
Kinstaの開発アドボケートアナリスト、ウェブ開発者。仕事以外の時間は、コードを書いたり、ニュースレター向けの有益情報を探したり、コーヒーを飲んだりして過ごしている。
コメントを残す