middleman で簡単なドキュメントサイトを作る

middleman

play-flyway のドキュメントサイトを作るのに middleman を使った。そのメモ。

インストール

$ gem install middleman

最低限のコマンド

middleman init でひな形を作成。

$ middleman init website

...

      create  website/.gitignore
      create  website/config.rb
      create  website/source/index.html.erb
      create  website/source/layouts/layout.erb
      create  website/source/stylesheets
      create  website/source/stylesheets/all.css
      create  website/source/stylesheets/normalize.css
      create  website/source/javascripts
      create  website/source/javascripts/all.js
      create  website/source/images
      create  website/source/images/background.png
      create  website/source/images/middleman.png

source/ 以下のファイルを編集していくことになる。

開発用サーバの起動は middleman server で。

$ bundle exec middleman server

できあがったら middleman build でHTML にエキスポートできる。

$ bundle exec middleman build

Markdown を使えるようにする

redcarpet を Gemfile に加える。オプション次第で GFM っぽくなる。

# Gemfile
gem "redcarpet"

# config.rb
set :markdown_engine, :redcarpet
set :markdown, :tables => true, :autolink => true, :gh_blockcode => true, :fenced_code_blocks => true

これでファイルの拡張子を .markdown にすると markdown で書けるようになる。

シンタックスハイライト

middleman-syntax を使う

# Gemfile
gem "middleman-syntax"

# config.rb
activate :syntax

感想

  • reloadとか勝手にしてくれるし使いやすかった。
  • middleman 流の asset の扱いがよくわかってない、というかまじめに調べてない。layout.erb で普通に script タグ書いたりしたけど、まあいっかという感じ。