docsifyとは
documentation site generator.
ドキュメントサイトを構築するツールです。
使ってみるとわかりますが、すごく手軽に使えます。
開発ドキュメントを書くのにピッタリです。
似たようなツールとして、gitbookやSphinxもこれまで使ってきましたが、
- gitbookはローカルで使うにはサポート切れ
- SphinxはPython使わないプロジェクトでPython環境構築するのしんどい
などあって、良いツールを探していましたが、やっと見つけました。
docsifyでできること
以下のような要件であれば、docsifyはちょうど良いと思います。
- Markdownでドキュメントを書きたい
- 書いたドキュメントをクラウド上でホスティングしたい
- ドキュメントはgitでソースコードと一緒に管理したい
- plantumlを使いたい
docsifyのいいところ
セットアップが簡単
# 初期化
npx docsify-cli init ./docs
# 以下の3ファイルが作成される
# ./docs/index.html
# ./docs/README.md
# ./docs/.nojekyll （Github Page用）
# ローカルでドキュメントサイト立ち上げ
npx docsify-cli serve docs
# http://localhost:3000にアクセスすると、README.mdの内容が表示される
これだけで済みます。
Node.jsの環境さえあれば、ライブラリのインストール不要で実行できます。
ビルド不要
docsifyは、MarkdownをコンテンツとするCMSと思えばよいです。
例えば、index.htmlと同じ階層にAWS.mdを作成すると、
ビルドなしでhttp://localhost:3000/#/AWSにてコンテンツ（AWS.mdの内容）を閲覧できます。
カスタマイズが簡単
テーマの変更、プラグインの追加等のカスタマイズはindex.htmlを編集するだけでOKです。
下記htmlのコメントを入れたところだけカスタマイズすればよいと思ってください。
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8" />
<title>my service documents</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<meta name="description" content="my service documents" />
<meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0" />
<!-- 好きなThemeを挿入 -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css"/>
<!-- スタイルをカスタマイズ -->
<style>
.markdown-section {
max-width: 90%;
}
</style>
</head>
<body>
<div id="app"></div>
<script>
// docsifyの設定
window.$docsify = {
name: 'service name',
// docsifyはSPA。ページを切り替えたときに左上にスクロールする設定
auto2top: true,
// サイドバーを表示。別途_sidebar.mdを書く必要あり。gitbookのSUMMARY.mdと同じ要領。
loadSidebar: true,
alias: {
'/.*/_sidebar.md': '/_sidebar.md' // 詳細はissueの301参照
},
plantuml: {
skin: 'classic' // plantumlのskinの設定
}
}
</script>
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
<!-- plantumlのプラグイン -->
<script src="//unpkg.com/docsify-plantuml/dist/docsify-plantuml.min.js"></script>
<!-- ソースコードのハイライト。既定はhtml,css,javascriptのみ。必要なものを追加する。 -->
<script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-python.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-typescript.min.js"></script>
</body>
</html>
デプロイ方法
公式サイトにGitHub Pages, GitLab Pages, Firebase Hosting, VPS, Netlify, AWS Amplifyへのデプロイ方法は記載があります。
https://docsify.js.org/#/deploy
僕はAWSのS3にデプロイしたかったので、以下がその方法です。
（CloudFront + S3 の静的サイトホスティング環境がある前提）
といっても大したことはしておらず、同期するだけです。
# 1. docsをS3に同期
aws s3 sync --delete $PWD/docs s3://my-service-docs
# 2. CloudFrontのキャッシュをinvalidate
aws cloudfront create-invalidation --distribution-id $DOCS_DISTRIBUTION_ID --paths "/*"