dev:mordiford

Wiki.js のすすめ

Author Avatar
hota 12月 09, 2017

知見を書き溜めて置く場所の重要性

ありますよね。

SNSに投げっぱなしにする弊害

  • Twitterとか、最近はMastodonとかのマイクロブログに知見を投げ捨てていませんか
  • いざ後で見返すときの検索性の低さ
    • 個人的にはTwitterだとTwilogとか使ってたけど、そういうのがない+全文検索が無いMastodonではより顕著
  • 追記やら修正やらと絶望的に相性が悪い
    • in_reply_to ついてればいいってもんでもない

ブログを書くハードル

  • なんかブログ記事って投稿時点で一定のオチがついてないと上げづらくないですか(は?)
  • これはわたしが完全に悪いんだけど、静的サイトジェネレータでブログ作った結果ブログ記事を書くハードルが上がった
  • これを書くのも遅れた

そうだ、Wiki に書き留めよう

  • 更新されて当たり前な仕組みなので
    • 更新履歴や版の管理が充実している
    • 気兼ねなく更新していける

Wiki エンジンを選ぶ

要件

  • Markdownで書きたい
    • それはそう。
    • 要はメモ書きなので、このためにわざわざ新しい記法を覚えるのは…
  • 自ドメインで運用したい
  • 静的サイトジェネレーターでなくてよい
  • permalinkは人間が読める形式であるべき

GitHub Wikiが適さない理由

  • 存在がリポジトリに依存する
    • Wiki用のリポジトリを作ってしまうのは一つの手だけど、そうじゃない感
  • 存在に気づきにくい
  • 狭い

GitHubの /docs + GitHub Pages を使わない理由

  • メモ書きがしたいのであってかっちりしたドキュメントを書きに来たわけではない

めんどいので結論

Wiki.js

  • タイトル回収。
  • https://wiki.js.org/
    • "An open source, modern and powerful wiki app built on Node.js, Git and Markdown."
  • Git (>= 2.7.4)と Node.js (>= 6.9.0) と MongoDB (>= 3.2) がある環境ならだいたい動く
    • MongoDB は主にユーザとメタデータの管理に使われている程度で、全体としては非常に軽量
    • 1core CPU/768MB RAMが要件
  • サジェストを含む検索機能が標準で備わっている
  • GitHub Flavored Markdown 準拠の Markdown 記法をサポート(一部独自の拡張有り)
    • YouTube等の動画の貼り付け、emojiの shortcode 、blockquote のスタイルなどがある
    • ちなみに Markdown のプレビューはその場で書いてる要素が反映されるタイプ(ここ好みが分かれるポイント)
  • 記事や画像などのコンテンツは Git で管理されており、任意のリポジトリを設定可能
    • 各記事は .md として、1回の編集が1 commitとして記録されている
    • セットアップウィザードで既に中身のあるリポジトリを指定すると構成通りにページが作成されるので復元にもなる
    • 前述の通り MongoDB が占める割合は低いので、万が一環境が吹き飛んでもコンテンツは(任意のgitリポジトリが存在している限り)復元可能
  • 様々な外部認証プロバイダ/OAuthを利用可能
    • Google ID, Microsoftアカウント、Facebook, GitHub, Slack, LDAP(Active Directory)
  • 現時点でユーザ側がアカウントを新規に作成することはできない
    • adminしかアカウントを作成する権限がない
    • 2018年にリリースされる 2.0 ではユーザによるregistrationが追加されると言っているが、現在 1.0.12

インストール

すごくやさしい。

公式Wiki(なんとdemoを兼ねている) https://docs.requarks.io/wiki を読んでパッケージ揃えるだけで良い。MongoDBもインストールして mongod 動かしておくだけでいい。

バージョン依存な知見をブログに書き残したくはないので常に公式Wikiを参照しよう。

使用例1 (個人使用)

  • https://wiki.maud.io/
  • 1core/2GBくらいのサーバを専有しています
  • 今まで複数のリポジトリに散らばっていたGitHub Wikiの中身を一通り持ってきています
  • Gitリポジトリは https://github.com/mordiford/wiki で、ユーザ登録に使われたメールアドレスがcommitterになっています

使用例2 (共同編集)

  • https://wiki.akane.blue/
  • 2core/4GBで他にもいろいろ走っているサーバです
  • 見ての通り、わたしが9月から運用しているMinecraftのマルチプレイ鯖での情報共有を目的としたWikiに使用しています
  • GoogleかGitHubのアカウントを使用したOAuthログインのみを有効化しています
  • ユーザ登録がないのは共同編集用途ではつらい。