設定の変更方法

CodiMDには様々な設定が用意されています。これはいずれもdocker-compose.ymlから環境変数として渡すことで変更可能です。具体的には次の部分が該当します。

  codimd:
      image: hackmdio/hackmd:2.4.1-cjk
      environment:
        - CMD_DB_URL=postgres://codimd:パスワード@database/codimd
        - CMD_USECDN=false

$ sudo docker-compose down
$ sudo docker-compose up -d

これで新しい設定が反映された状態になります。データは残っていますので安心してください。ただし一旦ログアウトされますので，必要に応じて再度ログインしてください。ここからは主だった設定内容について見ていきましょう。なお，今回はバージョン2.4.1を想定しています。

アカウント作成機能とゲストアクセスの制限

CodiMDは何も設定しないと次のような状態になります。

• 誰でもアカウントを作成可能
• ページのURLを知っている人はアカウントがなくても誰でも閲覧可能
• アカウントを持っている人のみページの新規作成可
• アカウントがない場合は編集は不可

つまりフルオープンに近い状態です。ただしURL自体はランダムな文字列なので，「⁠誰でもページが閲覧できるわけではない」という点は安心して大丈夫でしょう。気になるようならリバースプロキシー側で認証を付けるという手もあります。

まずアカウントの作成については，CMD_ALLOW_EMAIL_REGISTERをfalseにしておくことで無効化できます。この場合，次のコマンドを使えば手動でアカウント作成可能です。

$ cd /etc/codimd/
$ sudo docker-compose exec codimd ls ./bin/manage_users
You did not specify either --add or --del or --reset!

Command-line utility to create users for email-signin.
Usage: bin/manage_users [--pass password] (--add | --del) user-email
  Options:
    --add       Add user with the specified user-email
    --del       Delete user with specified user-email
    --reset     Reset user password with specified user-email
    --pass      Use password from cmdline rather than prompting

$ sudo docker-compose exec codimd ls ./bin/manage_users --add メールアドレス

しかしながらCodiMDのローカルアカウント機能はかなり貧弱です。管理者が動作確認の用途に使うと思っておいたほうが良さそうです。その代わりSAMLやLDAP，OAuth関連には一通り対応しているため，本格的な運用を行うならそちらを使いましょう。

アカウントの作成を制限できたら，アクセスできるのは「ページの作成者」か「正規の手順でアカウントを持っていてURLを知っている人」か「ゲストでURLを知っている人」のいずれかに限定できます。ここでゲストの権限を管理するのがページごとのパーミッションと全体の設定です。

まず，CodiMDはページごとにパーミッションを設定できます。これはページの作成者のみが変更でき，次のような選択肢が存在します。

Freely

ゲストも含めて誰でも閲覧・編集が可能

Editable

ゲストは閲覧可・編集不可，それ以外は閲覧・編集が可能

Limited

ゲストは閲覧・編集共に不可，それ以外は閲覧・編集が可能

Locked

ページ作成者のみが編集可，それ以外はゲストを含めて閲覧のみ可

Protected

ページ作成者のみが編集可，アカウント持ちは閲覧可・編集不可，ゲストは閲覧・編集ともに不可

Private

ページ作成者のみが閲覧・編集可，それ以外は閲覧・編集共に不可

図6　ページごとのパーミッションの選択

特に何も指定しなければ「Editable」が選択されます。つまりゲストもURLさえわかれば，閲覧は可能です。編集画面も表示はできますが，編集しようとするとログインを要求されます。

パーミッションの初期値やゲストの扱いは，次の環境変数で変更します。

• CMD_ALLOW_ANONYMOUS：trueにするとゲストはページの新規制限も含めて無制限に許可されます。初期値はfalseになっています。
• CMD_ALLOW_ANONYMOUS_VIEWS：falseにするとEditableやLockedが選択できなくなります。初期値はtrueになっています。
• CMD_ALLOW_ANONYMOUS_EDITS：falseにするとFreelyが選択できなくなります。初期値はtrueになっています。
• CMD_DEFAULT_PERMISSION：ページ作成時のパーミッションです。初期値はeditableになっています。

ゲストアクセスを完全無効化したいのなら，次のように設定すると良いでしょう。

CMD_ALLOW_ANONYMOUS_VIEWS=false
CMD_ALLOW_ANONYMOUS_EDITS=false
CMD_DEFAULT_PERMISSION=limited

特殊な書式とエクスポート機能

CodiMDは単なるMarkdownだけでなく，動画や図版の埋め込み・生成を含めた拡張書式もサポートしています。

図7　埋め込み系は{%名前 URL}のように書く

図8　生成系はFenced code blockにプロパティを追加する

特にMermaidやVega-Liteのように拡張性が高く，（⁠うまく使えば）見栄えの良い書式にも対応しているので，きれいな図をたくさん用意したい場合に役に立つことでしょう。

内容が固まったらURL以外の方法で共有する方法として，次のようなフォーマットへエクスポート可能です。

• Markdown
• HTML
• PDF
• Pandoc経由でのEPUB3やLaTeX，reStructuredText，ODT（OpenDocument Text⁠）⁠，Wordなど

図9　作成したMarkdownは様々なフォーマットにエクスポートできる

PDFとPandocはベータ扱いです。おそらくもっとも便利なのがPDFでしょう。内部ではmarkdown-pdfを使っているらしく，日本語の生成にも対応しています。ただし埋め込まれるフォントが部分的にSource Han SansのTC（繁体字）やSC（簡体字）になるらしく，句読点を含めて一部おかしくなる点には注意が必要です。うまく回避する方法が見つかっていないため，気になるようならMarkdownをダウンロードして自分で生成してしまったほうが楽かもしれません。

その他の設定項目

ドメイン名やサービスURL，パスが決まっているなら「CMD_DOMAIN⁠」⁠，「⁠CMD_URL_PATH」あたりを設定しておきましょう。

社内で限定して運用するなら，「⁠CMD_AUTO_VERSION_CHECK」はfalseにしたほうがいいかもしれません。これは現在実行中のバージョンとIPアドレスを，CodiMDの開発者に通知してしまうからです。

設定項目自体はそこまで多くないため，一通り読んでおくとあとあと楽かもしれません。

CodiMDは「Markdownに慣れている」メンバー間で，リアルタイムに共同編集したい場合には非常に便利なツールです。自分でデプロイ・運用が面倒な場合も，より高機能なHackMDが，いくつかの条件付きで無料で利用できますし，有償のプランもあります。まずはこちらの無料プランで試してみて，フィーリングが合うようなら選択肢にいれてみてもいいのではないでしょうか。