docs-slate

ドキュメントは何で書いていますか?

sphinxとか定番です。

でもslateとか先駆的なのでオススメです(と言っても若干古い)。

$ git clone https://github.com/lord/slate
$ cd !$:t
$ bundle install
$ bundle exec middleman server

見た目のカスタマイズにはsource/layouts/layout.erbとかを編集します。htmlでなくerbで書きます。cssはscssで書きますので、source/stylesheets/_foo.scssを用意して、source/stylesheets/{print.css.scss,screen.css.scss}などからインポートします。

gitlab-ciでdeployする場合はmiddlemanを使いまので、以下のような感じ。

image: ruby:2.3

pages:
  script:
  - apt-get update -yqqq
  - apt-get install -y nodejs
  - bundle install
  - bundle exec middleman build
  artifacts:
    paths:
    - public
  only:
  - master

これはハマりポイントなのですが、GitLab Pagesは、pathsをpublicで指定しないとDeployに何故か失敗します。

更に、Middlemanはbuildディレクトリにビルドされるのがデフォルトで、これを設定ファイルであるconfig.rbにて指定しなければなりません。

configure :build do
  set :build_dir, 'public'
end

それと、bundleはnodejsをインストールしなければ使えなかった気がします。インストールしないとbundleがないと言われるし、gem i bundlerでインストールすると、middleman buildが何故か失敗するような感じだった覚えがあります。正直、よく分からん…。

個人的には、Middlemanはもう使いたくないのですが、他のDoc Genよりはマシということで。