ドキュメントサイトの設置

過去に調べたこと考えたこと、決めたことについては、まずココを見ればよいというサイトを設置する。

どうしても散らばってしまうメモ、少し時間をおくと書いたことすら忘れてしまうメモを一箇所にまとめ、過去に調べたこと、考えたこと、決めたことについては、まずココを見ればよいというサイトを設置する。

暫定解

Markdownで書き、gitのリポジトリで管理した文書を、静的サイトジェネレーター(Hugo)で見やすくして、出先のスマホやタブレットからも見られるようにNetlifyにデプロイすることにした。

Hugo + Docsy

Hugoは、brewで直接インストール。最近よくやるようなコンテナでの環境構築はしなかった。

$ brew install hugo
$ hugo version
Hugo Static Site Generator v0.74.3/extended darwin/amd64 BuildDate: unknown

Hugoのテーマは、シンプルでオーソドックスなのがよいと感じたのでDocsyを選んだ。

正攻法だとhugo server -Dしたときにワーニングが出たり、期待したようにメニューが表示されず、解決するにはあれこれ設定を調べる必要があったので、リポジトリのREADMEのおすすめに従って、docsy-exampleを丸ごとcloneする。

--depth 1を付けると、あとで自分のリポジトリにpushするときにエラーとなるので、付けずにcloneする。

$ git clone --recurse-submodules https://github.com/google/docsy-example.git
$ cd docsy-example
$ hugo server -D

ブラウザでhttp://localhost:1313/にアクセスして表示を確認する。

あとは、Docsyのユーザガイドを読んで、表示を確認しながら、config.tomlを編集する。

実際の文書データは、content/enを参考にしながらcontent/jaの配下に作成した。

Netlify

GitHubと連携したアカウントの作成、リポジトリの連携は簡単。

いざデプロイすると、エラーになった。

ERROR 2020/08/08 12:36:32 error: failed to transform resource: SCSS processing failed: file "stdin", line 6, col 1: File to import not found or unreadable: ../vendor/bootstrap/scss/bootstrap.

CSSのカスタマイズはしないのでPostCSSの導入は必要ないはずなのだけれど、何か関連しているのではと思ったが、それは思い違い。

PostCSSの導入の有無は関係なく、docsyリポジトリのサブモジュール(bootstrap)がcloneされないため、配下のファイルが見つからない、というのが実際のよう。

netlify.tomlでコマンドを指定する箇所で、hugoを実行する前にサブモジュールの更新をする。

[build]
publish = "public"
command = "cd themes/docsy && git submodule update -f --init --recursive && cd ../.. && hugo --gc --minify"

[context.production.environment]
HUGO_VERSION = "0.74.3"
HUGO_ENV = "production"
HUGO_ENABLEGITINFO = "true"

Netlifyでのgit cloneはsubmoduleも再帰的にcloneをする(オプションの指定はできない)という記載もあったが、実際にはサブモジュール(docsy)のサブモジュール(bootstrap)のcloneは行われていないのではないかと思う。

ここまでの作業で、Netlifyの付けたサブドメインでのアクセスはできるようになった。

独自ドメインの設定

以前登録して、未使用のドメイン(mizutamauki.com)があったので、サブドメインを付けて、docs.mizutamauki.comをこのサイトのドメインとして設定する。ネームサーバはNetlifyの物を使った。

NetlifyのDomain settingsをクリックした先で諸々の操作する。ポイントは、

TypeがCNAME、Nameがdocs、ValueがNetlifyの付けたサブドメインになるレコードを追加する
表示される４つのネームサーバを、ドメインの登録先に設定する
HTTPSは自動的に設定される
じっと待つ(反映されるまで30分から1時間くらいかかった)

ここまでの作業で、 https://docs.mizutamauki.com/ へのアクセスでサイトが表示できるようになった。

検索機能

Google Custom Search Engineを使って、検索ができるようにする。

Navigation and Searchに書かれた手順で作業する。

Custom Search pageの新しい検索エンジンをクリックして諸々設定
「検索するサイト」には、https://docs.mizutamauki.com/を設定する
「検索エンジンID」を取得して、config.tomlの記載を変更
content/ja配下に、search.mdを作成する

検索結果が表示されるようになるまで数日かかるようなので、あとで確認することにして、今回の作業はここまで。

参考サイト

最終更新 August 9, 2020