はじめに
手順書等のドキュメントを Markdown で書いて Git でバージョン管理したい！
でも、周りの方が必ずしも Markdown や Git
に明るくなかったり、Markdown → PDF 等に変換しても結局それを配るのが手間だったり。。。
そこで、
- Markdown で書く
- GitLab でバージョン管理する
- 静的サイトとして GitLab Pages にホスティングする
- ファイルが更新されたら自動でサイトも更新
- サイトから簡単に編集できる
という環境を今話題の(もう落ち着いたかな？) GitLab + GitLab CI (+ 静的サイトジェネレータの Hugo)を使って作ってみます。
サンプル
以下に公開していますので、参考になれば。
環境
- Mac OS 10.13.4
- GitLab.com
Hugo のインストール
まずは Hugo をインストールします。
$ brew install hugo
Hugo サイトの生成
新規ディレクトリを作成して、そこで Hugo サイトを生成します。
$ mkdir hugo-sample
$ cd hugo-sample
$ hugo new site .
Hugo テーマのインストール
Hugo はサイトの目的に応じていろんなテーマを適用させることができます。
Hugo themes website の中から、今回はドキュメント用ということで Documentation タグの付いたものから選びます。
なんとなく気に入ったので、Docdock を適用することにしました。
ではさっそく、Git のサブモジュールとして Docdock をインストール & イニシャライズします。
$ git init
$ git submodule add https://github.com/vjeantet/hugo-theme-docdock.git themes/docdock
$ git submodule init
$ git submodule update
コンフィグの設定
まずはサンプルサイトをプロジェクトルートにコピーします。
$ cp themes/docdock/exampleSite/* .
次に、config.toml を編集します。
baseURL = "https://otuhs_d.gitlab.io/hugo-sample"
languageCode = "en-us"
DefaultContentLanguage = "en"
title = "DocDock Documentation"
theme = "docdock"
# themesdir = "../.."
pygmentsCodeFences = true
pygmentsStyle = "monokailight"
...
[params]
editURL = "https://gitlab.com/otuhs_d/hugo-sample/edit/master/content/"
...
- 1 行目の
baseURLをホスティングする GitLab Pages の URL に書き換える- 具体的には、
https://"自分のユーザー名".gitlab.io/"プロジェクト名"
- 具体的には、
- 6 行目の
themeをdocdockに書き換える - 7 行目をコメントアウトする
- 31 行目の
editURLを GitLab の編集ページの URL に書き換える- 具体的には、
https://gitlab.com/"自分のユーザー名"/"プロジェクト名"/edit/master/content/
- 具体的には、
.gitlab-ci.yml の作成
GitLab CI て動かすジョブは .gitlab-ci.yml に定義します。
今回でいうと、push されるたびに Hugo サイトを更新(生成)するというジョブです。
image: registry.gitlab.com/pages/hugo:latest
variables:
GIT_SUBMODULE_STRATEGY: recursive
pages:
stage: deploy
environment: production
script:
- hugo
artifacts:
paths:
- public
GitLab に Push
あとは push してあげれば、GitLab CI のジョブがはしり、GitLab Pages にサイトがホスティングされます。
URLは、Settings > Pages から確認できます。
Note:
GitLab CI のステータスやログは、CI/CD>PilelinesまたはJobsから確認できます。
コンテンツの編集
もちろんローカルでファイルを編集して push して...としてもいいのですが、各ページ下部の Improve this page から GitLab の編集ページへ飛ぶことができます。（config.toml の editURL を変えたのはこのためです）
Git に慣れていない非エンジニアの方でも簡単に修正できて非常に便利だと思います。
Hugo のお作法的なところや、新規ページの作成方法などの詳細はここでは省きます。
基本的には content ディレクトリ以下にサブディレクトリを切って、その中に Markdown ファイルを置いていく形になります。
おわりに
とりあえず始めてみる！というところまで説明してみました。いかがだったでしょうか？
私自身 Hugo 触りたてで分かりづらいところも多かったと思いますが、お役に立てれば幸いです。