Help us understand the problem. What is going on with this article?

GitLab CI + GitLab Pages + Hugo を使ってドキュメント管理環境を構築する

More than 1 year has passed since last update.

はじめに

手順書等のドキュメントを 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 を編集します。

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 行目の themedocdock に書き換える
  • 7 行目をコメントアウトする
  • 31 行目の editURL を GitLab の編集ページの URL に書き換える
    • 具体的には、 https://gitlab.com/"自分のユーザー名"/"プロジェクト名"/edit/master/content/

.gitlab-ci.yml の作成

GitLab CI て動かすジョブは .gitlab-ci.yml に定義します。
今回でいうと、push されるたびに Hugo サイトを更新(生成)するというジョブです。

.gitlab-ci.yml
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 から確認できます。

スクリーンショット 2018-06-20 0.28.54.png

Note:
GitLab CI のステータスやログは、CI/CD > Pilelines または Jobs から確認できます。

コンテンツの編集

もちろんローカルでファイルを編集して push して...としてもいいのですが、各ページ下部の Improve this page から GitLab の編集ページへ飛ぶことができます。(config.tomleditURL を変えたのはこのためです)

Git に慣れていない非エンジニアの方でも簡単に修正できて非常に便利だと思います。

スクリーンショット 2018-06-20 0.33.34.png

Hugo のお作法的なところや、新規ページの作成方法などの詳細はここでは省きます。
基本的には content ディレクトリ以下にサブディレクトリを切って、その中に Markdown ファイルを置いていく形になります。

おわりに

とりあえず始めてみる!というところまで説明してみました。いかがだったでしょうか?
私自身 Hugo 触りたてで分かりづらいところも多かったと思いますが、お役に立てれば幸いです。

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした