ここから少しアップデートしたのでメモ。
リポジトリ
特徴
markdown -> html への変換には aglio、ローカルサーバーは --server オプションを使う
ローカルで markdown ファイルを html に変換するのに aglio を使うところは以前と同じ。
改めて調べてみると、--server というオプションでライブリロード機能つきのローカルサーバーの起動までやってくれるらしく、browserSync は不要だった。
また、ポート番号については README に記載されていないが、-p オプションで指定できた。
参考：Support for different port? · Issue #12 · danielgtaylor/aglio
$ ./node_modules/aglio/bin/aglio.js Usage: node_modules/aglio/bin/aglio.js [options] -i infile [-o outfile -s] オプション: -i, --input Input file -o, --output Output file -t, --theme Theme name or layout file [デフォルト: "default"] -f, --filter Sanitize input from Windows [真偽] [デフォルト: true] -s, --server Start a local live preview server -h, --host Address to bind local preview server to [デフォルト: "127.0.0.1"] -p, --port Port for local preview server [デフォルト: 3000] -v, --version Display version number [デフォルト: false] -c, --compile Compile the blueprint file [デフォルト: false] -n, --include-path Base directory for relative includes --verbose Show verbose information and stack traces [デフォルト: false] --theme-variables Color scheme name or path to custom variables [デフォルト: "default"] --theme-condense-nav Condense navigation links [真偽] [デフォルト: true] --theme-full-width Use full window width [真偽] [デフォルト: false] --theme-template Template name or path to custom template [デフォルト: "default"] --theme-style Layout style name or path to custom stylesheet --theme-emoji Enable support for emoticons [真偽] [デフォルト: true] 例: node_modules/aglio/bin/aglio.js -i Render to HTML example.apib -o output.html node_modules/aglio/bin/aglio.js -i Start preview server example.apib -s node_modules/aglio/bin/aglio.js Theme colors --theme-variables flatly -i example.apib -s node_modules/aglio/bin/aglio.js Disable options --no-theme-condense-nav -i example.apib -s See https://github.com/danielgtaylor/aglio#readme for more information
（コマンド例）
$ aglio -i src/index.md -p 8080 --server
複数ファイルの分割は <!-- include(xxx.md) --> で実現
参考：https://github.com/danielgtaylor/aglio#including-files
エントリーポイントとなるファイルで
FORMAT: 1A
<!-- include(xxx.md) -->
としておくと、別のファイルを読み込むことができる。
これで API 定義を複数のファイルに分割することができる。
これ自体は以前調べたときにも把握はしてたようだが、モックサーバー用ライブラリ api-mock の制限で断念したようだった。
が、次に示すようにモックサーバを api-mock から drakov というライブラリに変更したのでこの問題は解決した。
モックサーバには api-mock のかわりに drakov を使用
以前調べたときは api-mock を使おうとしていたらしいが、
今 Node のバージョン 7.1.0、npm のバージョン 3.10.9 でインストールしようとしたところエラーになってしまった。
$ npm i -g api-mock /usr/local/bin/api-mock -> /usr/local/lib/node_modules/api-mock/bin/api-mock > protagonist@1.2.6 install /usr/local/lib/node_modules/api-mock/node_modules/protagonist > node-gyp rebuild CXX(target) Release/obj.target/libmarkdownparser/drafter/ext/snowcrash/ext/markdown-parser/src/ByteBuffer.o clang: error: invalid deployment target for -stdlib=libc++ (requires OS X 10.7 or later) make: *** [Release/obj.target/libmarkdownparser/drafter/ext/snowcrash/ext/markdown-parser/src/ByteBuffer.o] Error 1 gyp ERR! build error gyp ERR! stack Error: `make` failed with exit code: 2 gyp ERR! stack at ChildProcess.onExit (/usr/local/lib/node_modules/npm/node_modules/node-gyp/lib/build.js:276:23) gyp ERR! stack at emitTwo (events.js:106:13) gyp ERR! stack at ChildProcess.emit (events.js:191:7) gyp ERR! stack at Process.ChildProcess._handle.onexit (internal/child_process.js:215:12) gyp ERR! System Darwin 14.5.0 gyp ERR! command "/usr/local/Cellar/node/7.1.0/bin/node" "/usr/local/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js" "rebuild" gyp ERR! cwd /usr/local/lib/node_modules/api-mock/node_modules/protagonist gyp ERR! node -v v7.1.0 gyp ERR! node-gyp -v v3.4.0 gyp ERR! not ok
この Issue が関係している？Node のバージョン 6 系からうまくインストールできないらしい。
install failed at protagonist package · Issue #53 · localmed/api-mock
しかたないので
https://apiblueprint.org/tools.html#mock-servers
の一番上にあった drakov にした。
drakov は対象の markdown ファイルを指定する際
$ drakov -f "src/**/*.md"
というように正規表現で指定することができるので、ファイルが複数に分割されていても問題ない。
" でくくらないと期待通りに動かないので注意（シェル環境が zsh だったからかも）
また、--watch オプションをつけておくと markdown ファイルの変更を検知して自動的にリロードしてくれる。
（コマンド例）
$ drakov -f "src/**/*.md" -p 8081 --watch
TODO
結局いまだに dredd というツールを調べられていない。
