Docusaurusでサイトを立てる
はじめに
このサイトはDocusaurus 3.0で作られています。このサイトを立ち上げるために行ったことをまとめました。
サーバーの確保
概要
- スターサーバーフリーの無料無広告プランを契約
- 無料無広告プランではPHPが使えない、ゆえにWordPressも使えない
- 手作業でHTMLを書くのは面倒なので「静的サイトジェネレーター」と呼ばれるアプリを使ってサイト構築することにする
システムの選定
概要
- いくつかある静的サイトジェネレーターのうち「Docusaurus」を選ぶ
- https://docusaurus.io/
- 長文の技術文書の公開が主たる用途だが、個人ブログや企業サイトも作成できる
- Windows,MacOS,Linuxに対応
- 原稿はマークダウン記法で書く
- マークダウンでは表現しきれない高度なページを作りたい時はMDX記法を使う
- 欠点：GUIを持たない、日本語資料少ない
インストール
Node.jsのインストール
概要
- Docusaurusのインストールおよび起動に「Node.js」が必要
- Windows,MacOS,Linuxに対応
- 公式サイトからインストーラを入手してインストールする
Docusaurusのインストール
概要
- MacOSの付属アプリ「ターミナル」を使ってインストールする(Windowsの場合はPowerShell)
手順
-
ここでは仮に
書類フォルダの中に以下の配置でDocusaurusをインストールするものとする/書類
└─/Docusaurus
└─/mysite
└─(Docusaurusシステム一式) -
Finderで
Docusaurusフォルダを新規作成 -
ターミナルを開く
-
ターミナルに以下コマンドを入力して[Enter]押
cd <<Docusaurusフォルダのパス名>>フォルダのパス名を知る方法: Finderでフォルダを右クリックし且つ[option]を同時押→右クリックメニューのメニュー項目に現れる「○○○○のパス名をコピー」という項目を選ぶ→フォルダのパス名がクリップボードにコピーされる
-
ターミナルに以下コマンドを入力して[Enter]押
npx create-docusaurus@latest mysite classic -
もしも
Ok to proceed? (y)というメッセージが表示されたらキーボードの[Y]を押しさらに[Enter]押 -
Finderに戻り、Docusaurusフォルダの中にmysiteフォルダが作られその中にシステム一式およびサンプルサイトがインストールされていることを確認する
/書類
└─/Docusaurus
└─/mysite
├─/blog
├─/docs
├─/node_modules
├─/src
│ ├─/components
│ ├─/css
│ └─/pages
├─/static
│ └─/img
├─babel.config.js
├─docusaurus.config.js
├─package-lock.json
├─package.json
├─README.md
└─sidebars.js -
了
プレビューの起動
手順
- ターミナルを開く
- ターミナルに以下コマンドを入力して[Enter]押
cd <<mysiteフォルダのパス名>>フォルダのパス名を知る方法: Finderでフォルダを右クリックし且つ[option]を同時押→右クリックメニューのメニュー項目に現れる「○○○○のパス名をコピー」という項目を選ぶ→フォルダのパス名がクリップボードにコピーされる
- ターミナルに以下コマンドを入力して[Enter]押
npm start - ウェブブラウザが起動してサンプルサイトのプレビューが表示されることを確認する
- 了
注記
プレビューを終了するには、ターミナルに戻ってキーボードの[control]と[C]を同時押する
サイト構成の確認
-
ページ種類
- Docusaurusのウェブページは「文書」「ブログ記事」「ページ」の3種類ある
- 文書
- 取扱説明書のような長文の技術文書を想定
- 複数の原稿ファイルで1つの文書が構成される
- 原稿を
docsフォルダに入れれば文書として扱われる - サンプルサイトでは、ナビゲーションメニューバーの「Tutorial」をクリックすると文書のページ一覧が表示される
- ブログ記事
- 個人のブログ記事を想定
- 原稿を
Blogフォルダに入れればブログ記事として扱われる - サンプルサイトではナビゲーションメニューバーの「Blog」をクリックするとブログ記事一覧が表示される
- ページ
- 汎用的でシンプルなウェブページ
- 原稿を
src/pagesフォルダに入れればページとして扱われる - サンプルサイトでは
src/pages/index.jsがトップページに設定されている
-
ナビゲーションメニュー
- 画面上端のナビゲーションメニューには「(サイトタイトル)」「Tutorial」「Blog」「(GitHubへのリンク)」「(ダークモードへの切替ボタン)」が配置されている
- これら項目は設定ファイル
docusaurus.config.jsの書き換えで変更できる
-
フッター
- 画面下端にはフッターがありSNSへのリンクなどが配置されている
- これら項目は設定ファイル
docusaurus.config.jsの書き換えで変更できる
サイトのカスタマイズ
トップページの変更
概要
- サンプルサイトでは
src/pages/index.jsがトップページに設定されている - 文書がトップページになるよう設定を変更する
手順
docusaurus.config.jsをテキストエディタで開く- presets欄を以下のように書き換え、保存する
書換前
docs: {
sidebarPath: './sidebars.js',
// Please change this to your repo.
// Remove this to remove the "edit this page" links.書換後
docs: {
routeBasePath: '/',
sidebarPath: './sidebars.js',
// Please change this to your repo.
// Remove this to remove the "edit this page" links. docs/intro.mdファイルをテキストエディタで開く- テキスト冒頭を以下のように書き換え、保存する
書換前
---
sidebar_position: 1
---書換後
---
slug: /
sidebar_position: 1
---備考：「slug: /」はこのページがトップページであることの目印
src/pages/index.jsを削除する- トップページの変更が正しく行われたことをプレビューで確認する
- 了
メニューバーの変更
概要
- メニュー項目「Tutorial」の項目名を「HOME」に変更する
- メニュー項目「Blog」をメニューバーから消す
- GitHubへのリンクをメニューバーから消す
手順
docusaurus.config.jsをテキストエディタで開く- themeConfig欄を以下のように書き換え、保存する
書換前
items: [
{
type: 'docSidebar',
sidebarId: 'tutorialSidebar',
position: 'left',
label: 'Tutorial',
},
{to: '/blog', label: 'Blog', position: 'left'},
{
href: 'https://github.com/facebook/docusaurus',
label: 'GitHub',
position: 'right',
},
],書換後
items: [
{
type: 'docSidebar',
sidebarId: 'tutorialSidebar',
position: 'left',
label: 'HOME',
},
], - メニューバーの修正が正しく行われたことをプレビューで確認する
- 了
サイドバーの表示/非表示切替
概要
- 左サイドバー(docsフォルダ内原稿ファイルの一覧を表示する部分)の表示/非表示をクリックで切替できるようにする
手順
docusaurus.config.jsをテキストエディタで開く- themeConfig＞docs欄を書き換える。ただしDocusaurusシステムインストール直後の
docusaurus.config.jsにはdocs欄自体がないので、欄ごと追記する書換前
themeConfig: {書換後
themeConfig: {
docs: {
sidebar: {
hideable: true,
},
}, - サイドバーの修正が正しく行われたことをプレビューで確認する
- 了
サイドバー表示項目のグループ化(実施しませんでした)
概要
- 左サイドバーに表示される
docsフォルダ内原稿ファイルの一覧を章ごとに(カテゴリごとに)グループ化して表示する
手順
- Finderで、
docsフォルダ内に、category-01フォルダを新規作成する category-01フォルダ内に、テキストエンコーディングUTF-8のテキストファイルを新規作成し、ファイル名を_category_.jsonとする_category_.jsonをテキストエディタで開く_category_.jsonの内容として以下を記述し、保存する書き換え前(新規作成)
書き換え後
{
"label": "章1",
"position": 2,
"link": {
"type": "generated-index",
"description": "この章の概要をここに記述してください"
}
}備考：
"label" 章タイトル、フォルダ名称そのままを章タイトルとして使いたくない時に使う
"position" 表示位置、たとえばここで2を指定すれば上から2番目に固定される
"link": 章タイトルをクリックした場合の挙動、ここで type:generated-index を指定すると、catecgory-01フォルダ内にある原稿ファイルの一覧をページとして自動生成して表示する- 了
サイドバー表示項目の折りたたみ/展開(実施しませんでした)
概要
- 左サイドバーに表示される
docsフォルダ内原稿ファイルの一覧が章ごとに(カテゴリごとに)グループ化された状態で、ひとつの章を(ひとつのカテゴリを)展開すると、他の階層グループが折りたたまれるようにする
手順
docusaurus.config.jsをテキストエディタで開く- themeConfig＞docs欄を書き換える。ただしDocusaurusシステムインストール直後の
docusaurus.config.jsにはdocs欄自体がないので、欄ごと追記する書換前
themeConfig: {書換後
themeConfig: {
docs: {
sidebar: {
autoCollapseCategories: true,
},
}, - サイドバーの修正が正しく行われたことをプレビューで確認する
- 了
複数文書への対応(実施しませんでした)
概要
- インストール直後のDocusaurusはひとつのdocsフォルダしか持たず、ひとつの文書しか掲載できない。設定を変更して、複数の文書を掲載できるようにする
手順
docusaurus.config.jsをテキストエディタで開く- themeConfig＞navbar欄を書き換える(項目追加する)
書換前
items: [
{
type: 'docSidebar',
sidebarId: 'tutorialSidebar',
position: 'left',
label: 'HOME',
},書換後
items: [
{
type: 'docSidebar',
sidebarId: 'tutorialSidebar',
position: 'left',
label: 'HOME',
},
{
type: 'docSidebar',
sidebarId: 'additionalSidebar',
position: 'left',
label: 'DOCS',
}, docusaurus.config.jsを保存して閉じるsidebar.jsをテキストエディタで開く- 以下の部分を書き換える。dirName項目が書き換えられていることに注意
書換前
tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],書換後
tutorialSidebar: [{type: 'autogenerated', dirName: 'home'}],
additionalSidebar: [{type: 'autogenerated', dirName: 'docs'}],備考：この設定を書き換えて以後は、原稿ファイルを収める場所は
docsフォルダではなく、docs/homeおよびdocs/docsフォルダになる。 sidebar.jsを保存して閉じる- メニューバーおよびサイドバーの修正が正しく行われたことをプレビューで確認する
- 了
サイト内検索機能の追加(バージョンアップで下記方法が使えなくなったので外しました)
概要
- プラグインをインストールしてサイト内検索機能を追加する
- 検索対象を文書のみとし、ブログ記事とページは検索対象から外す
- 前手順で文書1ページ目がトップページであると設定したので(
docs: {routeBasePath: '/',)、それに合わせて設定する
手順
-
ターミナルを開く
-
ターミナルに以下コマンドを入力して[Enter]押
cd <<mysiteフォルダのパス名>>フォルダのパス名を知る方法: Finderでフォルダを右クリックし且つ[option]を同時押→右クリックメニューのメニュー項目に現れる「○○○○のパス名をコピー」という項目を選ぶ→フォルダのパス名がクリップボードにコピーされる
-
ターミナルに以下コマンドを入力して[Enter]押
npm install --save @easyops-cn/docusaurus-search-local -
インストールが完了したら
docusaurus.config.jsをテキストエディタで開く -
themes欄を書き換える。ただしDocusaurusシステムインストール直後の
docusaurus.config.jsにはthemes欄自体がないので、欄ごと追記する書換前
themeConfig:
({
中略
})書換後
themeConfig:
({
中略
})
themes: [
[
require.resolve("@easyops-cn/docusaurus-search-local"),
({
indexDocs: true,
indexBlog: false,
indexPages: false,
docsRouteBasePath:"/",
hashed: true,
language: ["en", "ja"],
searchBarPosition: "auto",
searchBarShortcutHint: true,
}),
],
],
注記
上記例では検索対象言語として「英語」と「日本語」が指定してある。次の手順にて、サイトで使用する言語を明示的に設定する。
使用言語の設定
概要
- サイトで使用する言語として「日本語」を設定する
手順
docusaurus.config.jsをテキストエディタで開く- i18n欄を以下のように書き換え、保存する
書換前
i18n: {
defaultLocale: 'en',
locales: ['en'],
},書換後
i18n: {
defaultLocale: 'ja',
locales: ['ja'],
}, - 了
サイトタイトルの変更
概要
- サイトタイトルを「Ducaneko's Site」に変更する
- タグライン(ウェブサイトのキャッチフレーズ)を「Cat is watching you.」に変更する
手順
docusaurus.config.jsをテキストエディタで開く- const config欄の冒頭部分を以下のように書き換え、保存する
書換前
const config = {
title: 'My Site',
tagline: 'Dinosaurs are cool',
favicon: 'img/favicon.ico'書換後
const config = {
title: 'Ducaneko\'s Site',
tagline: 'Cat is watching you.',
favicon: 'img/favicon.ico',備考：プログラミングの記号としてでなく文字として
'(アポストロフィー記号)を使いたい時は、\(バックスラッシュ記号)を加えて\'と入力する - themeConfig欄を以下のように書き換え、保存する
書換前
navbar: {
title: 'My Site',
logo: {
alt: 'My Site Logo',
src: 'img/logo.svg',
},書換後
navbar: {
title: 'Ducaneko\'s Site',
logo: {
alt: 'Ducaneko\'s Site Logo',
src: 'img/logo.png',
}, - メニューバーの修正が正しく行われたことをプレビューで確認する
- 了
注記
ロゴの設定を変更したため一時的に画面左上端のロゴイラストが消える。次の手順にて、ロゴを作成する。
ロゴの変更
概要
- 画面左上端に表示されているロゴの絵柄を変更する
手順
- Photoshop等のグラフィックアプリでロゴを作る
- 256x256ピクセル
- PNG形式
- ファイル名
logo.png
- 作成したロゴを
static/imgフォルダに保存する - ロゴの変更が正しく行われたことをプレビューで確認する
- 了
注記
ここでは作成しやすさを考慮しロゴをPNG形式で作ったが、ロゴはSVG形式ベクターファイルでもよい。
ファビコンの変更
概要
- ウェブブラウザのタイトルバーに表示されているロゴ(ファビコン)の絵柄を変更する
手順
- ファビコンに用いる.ico形式ファイルを作成できるアプリは少ないので、ここではオンラインサービスを用いてファビコンをつくるものとする
- ウェブサイト「Faviconジェネレーター」を開く : https://favicon-generator.mintsu-dev.com/
- 「変換する画像を選択する」ボタンをクリックする
- ファイル選択ダイアログでLogo.png(前手順で作成したもの)を選択する
- 作成するサイズとしてすべての選択肢にチェックマークを入れる
- 「画像を変換する」ボタンをクリックする
- 「ダウンロード」ボタンをクリックする
- ダウンロードしたファビコンを
static/imgフォルダに保存する(古いfavicon.icoを上書保存する) - ファビコンの変更が正しく行われたことをプレビューで確認する
- 了
フッターの変更
概要
- フッターに配置されている各SNSへのリンク(サンプル記述)を正しいものに書き換える
- 画面最下端のコピーライト表記を「©︎ (年表示) Ducaneko」に書き換える
手順
docusaurus.config.jsをテキストエディタで開く- footer欄を以下のように書き換え、保存する
書換前
links: [
{
title: 'Docs',
items: [
{
label: 'Tutorial',
to: '/docs/intro',
},
],
},
{
title: 'Community',
items: [
{
label: 'Stack Overflow',
href: 'https://stackoverflow.com/questions/tagged/docusaurus',
},
{
label: 'Discord',
href: 'https://discordapp.com/invite/docusaurus',
},
{
label: 'Twitter',
href: 'https://twitter.com/docusaurus',
},
],
},
{
title: 'More',
items: [
{
label: 'Blog',
to: '/blog',
},
{
label: 'GitHub',
href: 'https://github.com/facebook/docusaurus',
},
],
},
],
copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
},書換後
links: [
{
title: 'SNS',
items: [
{
label: 'Twitter',
href: 'https://twitter.com/ducaneko',
},
{
label: 'Misskey.io',
href: 'https://misskey.io/@ducaneko',
},
],
},
{
title: 'Works',
items: [
{
label: 'VRM Posing - Steam Community',
href: 'https://steamcommunity.com/profiles/76561199029854359/myworkshopfiles/?appid=1895630',
},
{
label: 'PIXIV',
href: 'https://www.pixiv.net/users/88922952',
},
],
},
{
title: 'More',
items: [
{
label: 'iomc - Minecraft Server',
href: 'https://misskey.io/@mc',
},
],
},
],
copyright: `Copyright © ${new Date().getFullYear()} Ducaneko, built with Docusaurus.`,
}, - フッターの変更が正しく行われたことをプレビューで確認する
- 了
その他
- 書誌情報のURL欄に正しいウェブサイトURLを記入する
docusaurus.config.jsの書き換え書換前
// Set the production url of your site here
url: 'https://your-docusaurus-site.example.com',書換後
// Set the production url of your site here
url: 'http://ducaneko.starfree.jp',
- 書誌情報のGitHubに関する項目を項目削除する
docusaurus.config.jsの書き換え書換前
// 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.書換後(該当箇所全削除)
- 「Edit this page」ボタンを消す
docusaurus.config.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/',書換後(二箇所とも該当箇所全削除)
- social card 画像(ページがSNSでシェアされる際にサムネイルとして使われる画像)を差し替える
- Photoshop等のグラフィックアプリでロゴを作る
- 1200x675ピクセル
- JPEG形式
- ファイル名social-card.jpg
- 作成した画像を
static/imgフォルダに保存する docusaurus.config.jsの書き換え書換前
themeConfig:
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
({
// Replace with your project's social card
image: 'img/docusaurus-social-card.jpg',書換後
themeConfig:
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
({
// Replace with your project's social card
image: 'img/social-card.jpg',
- Photoshop等のグラフィックアプリでロゴを作る
- CSSの書き換え
- プレビューを確認し、見栄えとして気になる部分を
src/css/custom.cssの書き換えで変更する - 右サイドバーの今表示されている箇所と対応する目次項目にアンダーラインを引く、など
- プレビューを確認し、見栄えとして気になる部分を
原稿の作成
サンプル原稿の削除
docsフォルダ内にあるintro.md以外の.mdファイルを、すべて削除する
intro.mdの編集
- 前手順でトップページとして設定された
docs/intro.mdの内容を書き換える - 原稿はマークダウン記法で記述し、テキストエンコーディングUTF-8、拡張子.mdのテキストファイルとして
docsフォルダに保存する
原稿の追加
- 原稿はマークダウン記法で記述し、テキストエンコーディングUTF-8、拡張子.mdのテキストファイルとして
docsフォルダに保存する
独立したウェブページの追加
- Docusaurusとは独立したウェブページをDocusaurusと併用したい場合は、HTMLファイルおよび挿絵を作成し、
staticフォルダに保存する。 - たとえば
http://example.comというドメイン名でDocusaurusを運用し且つウェブページをstatic/folder/page.htmlとして保存した場合、そのウェブページはhttp://example.com/folder/page.htmlというURLで公開される。
404ページの有効化
- 後述する「ビルド」を実行すると404ページ(URLが間違っている際に表示されるページ)も自動的に生成されるが、スターサーバーではDocusaurusの生成した404ページは無視され、スターサーバーの用意した広告付き404ページが表示される。
- Docusaurusの生成した方の404ページを有効にするため、
.htaccessファイルを作成し、使用する404ページを明示的に指定する.htaccessファイルとは、テキストエンコーディングUTF-8、拡張子.htaccessの、拡張子だけでファイル名のないテキストファイルである- MacOSでは
.htaccessファイルは不可視ファイルである。Finderでフォルダを開きキーボードの「command」＋「shift」＋「.」を同時押しすることで、フォルダの中の不可視ファイルが見えるようになる。 .htaccessファイルの中身は１行のみErrorDocument 404 /404.html
- 作成した
.htaccessファイルはstaticフォルダに保存する
ウェブサイトのビルド
概要
- ここまでサンプルウェブサイトをカスタマイズしてオリジナルのウェブサイトを構築してきた。サンプルウェブサイトにはDocusaurusのシステムが含まれている。読者にとっては無意味なデータである
- 「ビルド」コマンドを用いて、Docusaurusのシステムを含まない公開用のウェブサイトを出力する
手順
- ターミナルを開く
- ターミナルに以下コマンドを入力して[Enter]押
cd <<mysiteフォルダのパス名>>フォルダのパス名を知る方法: Finderでフォルダを右クリックし且つ[option]を同時押→右クリックメニューのメニュー項目に現れる「○○○○のパス名をコピー」という項目を選ぶ→フォルダのパス名がクリップボードにコピーされる
- ターミナルに以下コマンドを入力して[Enter]押
npm run build - Finderに戻って
mysiteフォルダを開き、以下のファイルフォルダ(公開用ウェブサイト)が作成されていることを確認する。/mysite
└─/build
├─/assets
├─/build
├─/img
├─/markdown-page
├─/search
├─(フォルダ名が文書タイトルのフォルダ)
├─404.html
├─index.html
├─search-index.json
└─sitemap.xml
ウェブサイトのアップロード
buildフォルダ内にあるファイルフォルダ一式をそのままウェブサーバーにアップロードすればウェブサイトは公開される- スターサーバーフリーであれば、契約時に指定されたFTPサーバーのルートディレクトリにファイルフォルダ一式をアップロードすれば、、指定されたサイトURL http://ducaneko.starfree.jp/ でサイトが公開される
ウェブサイトのバックアップ
- 「ビルド」コマンドを用いて
buildフォルダ内に出力されたファイルフォルダ一式は、Docusaurusのシステムを含んでいない。buildフォルダのバックアップを保存しただけでは不充分である。 mysiteフォルダ全てをバックアップしてしまえば簡単だが、それではファイルサイズが大きすぎると感じる場合は、以下ファイルフォルダだけバックアップを保存する。/書類
└─/Docusaurus
└─/mysite
├─/blog ←ブログコンテンツ
├─/docs ←文書コンテンツ
├─/src
│ ├─/css ←カスタムCSS
│ └─/pages ←ページコンテンツ
├─/static ←コンテンツ挿絵等
└─docusaurus.config.js ←mysiteの設定ファイル
Google検索への登録
手順
- GoogleIDを入手
- Google Search Consoleにログイン : https://search.google.com/search-console/about?hl=ja
- 所有確認用HTMLファイルをダウンロードし、
staticフォルダに保存 - ウェブサイトのビルドを実行
buildフォルダの直下に、先ほどの所有確認用HTMLファイルの複製があることを確認するbuildフォルダ内にあるファイルフォルダ一式をそのままウェブサーバーにアップロードすればウェブサイトは更新される- Google Search Consoleに戻り、「確認」を実行
- 確認完了のメッセージが表示されたことを確認する
- 了
注記
実際にGoogle検索に掲載されるようになるには2、3日かかる。
おわりに
静的サイトジェネレーターの注意点
Docusaurusやその他の静的サイトジェネレーターは原稿更新のたびにビルドを行います。静的サイトジェネレーターのバージョンアップによって以前はビルドできていたものができなくなったりします。このサイトもカスタムCSSの些細な構文ミスがバージョンアップにより許されなくなり構文ミスを修正したことがあります。
ビルドエラーが発生した際はエラーメッセージを注意深く読み、エラー箇所を修正してください。