書き散らかしたMarkdownメモをかっこよく活用する

Markdownのメモを適当に残しても、後で行方不明になることがよくあるので、
かっこよく活用できるような方法がないか色々試してみました。
１ファイルであれば、VSCodeやatomなどのプレビュー機能でもいいですが、もっと見やすものがないかなと。

とりあえず個人的な範囲で使うのが目的なので、次のような機能がありそうなものを探します。

• フォルダに適当に保存したMarkdownファイルをきれいに表示
• 単語の検索機能がある

せっかくメモしても、アウトプットがかっこよくないと、やる気が出ないのです。

試した対象はこちら。割と有名なものを選んでいるつもりです。

• Material for MkDocs
• GitBook (Legacy)
• Wiki.js
• Crowi

ちなみに、どれもサーバを立ててブラウザ経由で見るタイプのものです。

比較結果

いきなり結論。今回の目的だと、個人的には「Material for MkDocs」が一番目的にあっていそうでした。
見た目もかっこいいです。あと検索機能も（いまのところ）速くて使えます。

Material for MkDocs

• この用途に向いてそう
  • 個人的な手順メモなどをかっこよく活用する
• ○なところ
  • 日本語検索対応
  • コードブロック(```で囲んだ部分)にコピーボタンがつく
  • 注釈をきれいに表示できる(Admonition)
  • 普段はテキストエディタで読み書きできる。きれいにみたい時だけ使えばいいので楽
  • フォルダ構造に応じてメニューができるので楽
• ×なところ
  • ブラウザ経由での直接編集はできない

GitBook (Legacy)

• この用途に向いてそう
  • 長いドキュメントをMarkdownで書く
• ○なところ
  • 本をイメージしたシンプルなデザイン
  • 普段はテキストエディタで読み書きできる。きれいにみたい時だけ使えばいいので楽。
  • PDF変換機能あり
• ×なところ
  • 日本語検索未対応？
  • フォルダにあるMarkdownファイルのうち、どれを変換するか定義が必要(少しめんどう)
  • ブラウザ経由での直接編集はできない
  • 公式的にLegacyな位置付け(今後の機能追加は望み薄い？)
  • 新しいGitBook v2はクラウドサービスでローカル利用は未対応

Wiki.js

• この用途に向いてそう
  • 小規模チームでとりあえずナレッジ共有を始める
• ○なところ
  • ブラウザ経由での直接編集可能
  • Markdownのファイルとして保存されるため、他のツールが使いたくなっても移行がしやすい
  • ログイン機能あり
  • 画像アップロードにも対応
• ×なところ
  • 日本語検索未対応？
  • 環境構築が少しめんどう

Crowi

• この用途に向いてそう
  • 大規模チームでナレッジ共有する(完全にナレッジ共有用のWikiです)
• ○なところ
  • 日本語検索対応
  • 検索結果が見やすい
  • ブラウザ経由での直接編集可能
  • 他の人にも公開するかしないかが設定可能
  • 変更履歴や変更差分が確認できる
  • 「いいね」機能あり
  • PlantUMLと連携としてUMLがテキストで書ける(テキストなのでUML内の単語も検索対象)
• ×なところ
  • Markdownファイルとして保存されない
  • いまのところインポート・エクスポート機能が画面上になさそう(記事追加、取得のREST APIはある？)
  • 環境構築が少しめんどう(メンテも考えると、個人単位で手軽に始めるのは少しつらい)

補足

上記の○×などについて、少し補足。

Material for MkDocs

Material for MkDocsは、MarkdownをHTMLに変換するMkDocsがベースになっています。
見た目が変わるだけではなく、日本語検索対応、注釈表示機能、
タスクリスト表示などの拡張機能が追加されています。

表示サンプル

コードブロック(```で囲んだ部分)にコピーボタンがつく

コードブロック(```で囲んだ部分)の右上に、コピーポタンがつきます。
特にコマンドラインのメモから、コピーするときのに便利です。

注釈をきれいに表示できる(Admonition)

Markdownの標準的な記法ではないですが、注釈をきれいに表示できます。
よく見るページをよりかっこよくできます。

こう書くと、

!!! Warning
    いろいろ削除される

こんな表示になります。

Warning以外もあります。

GitBook (Legacy)

新しいGitBookは、Reduxのドキュメントなどに使われているようですが、現時点でローカルで利用する場合は、古い方のGitBook (Legacy)を使います。

本をイメージしたシンプルなデザイン

フォルダにあるMarkdownファイルのうち、どれを変換するか定義が必要

GitBook (Legacy)では、SUMMARY.mdで、変換対象のMarkdownファイルを指定する必要があります。どちらかというと、適当にフォルダに放り込んだファイルを変換してくれた方が楽なので、この辺が少し面倒です。

SUMMARY.md

# Summary

* [Home](README.md)
* [todo](docs/todo.md)

----

* [docker - 基本コマンド](docs/docker/基本コマンド.md)
* [docker - よく使うイメージ](docs/docker/よく使うイメージ.md)
* [docker - etc - memo](docs/docker/etc/memo.md)

公式的にLegacyな位置付け(今後の機能追加は望み薄い？)

新しい方のドキュメントにある、v2とLegacyな方の違いの説明に、静的サイト生成モデルはもう使っていないとあるので、Legacyな方の機能追加は望みが薄いかもしれないです。

We have moved away from the static site generator model, and no longer use the famous gitbook CLI to build documentation output.

少し前に書かれた情報だとGitBook (Legacy)の場合が多く、新しいGitBookの話はまだ少ないので注意です。

Wiki.js

表示サンプル

少しレトロな見た目。

Markdownのファイルとして保存されるため、他のツールが使いたくなっても移行がしやすい

公式ページの紹介にあるとおり、WikiなのにページのコンテンツをMarkrownファイルに保存します。なので、Markrownファイルを直接読んだり、Gitなどの連携も容易です。

Unlike other wiki software that save content in a database with a difficult to extract format, Wiki.js saves all your content directly into Markdown (.md) files and that content is automatically synced with your remote Git repository. Your content is therefore safe and readable directly from your Git repository.

Crowi

表示サンプル

検索結果が見やすい

インストール後に少し設定が入りますが、検索機能の結果が見やすいです。単語が含まれるページを一緒にみることができます。

PlantUMLと連携としてUMLがテキストで書ける

PlantUMLと連携してUMLもテキストで書けます。

テキストなので、検索結果にもひっかるようです。便利です。

いまのところインポート・エクスポート機能が画面上になさそう

ナレッジの共有と蓄積を目的とする場合、過去資産を活用できた方がよいのですが、Crowiをざっと見たかぎりそのようなUIがなさそうでした。一括インポートや、エクスポート的な機能があれば、、、気軽に始めれますが。
なお、REST APIで、ページ追加、ページ取得などもあるような情報があるので、それらを利用すればとりあえずはなんとかなりそうな気もします。

構築手順について

各ツールを実際試して見たい方は、構築手順のメモをまとめましたのでご参考に。

• 書き散らかしたMarkdownメモをかっこよく活用する【手順編】