ある種悲願でもあった、「BookStackにmermaid.jsを描画させる」が叶いました。

環境

  • BookStack v26.05.1
  • Apache 2.4
    • 実行ユーザーはwww-data
  • PHP-FPM 8.3
  • MySQL 8
  • Ubuntu 24.04

さっくりとした手順

  1. BookStackのルートディレクトリに移動します。
  2. Mermaid Viewerモジュールをインストールします。
  3. .envの編集をします（ハマった点）
  4. 設定を反映させます。
  5. 動作の確認を行います。

BookStackのルートディレクトリへ移動

cd /home/www-data/BookStack

筆者環境です。お使いの環境に応じてパスは変更してください

Mermaid Viewerモジュールをインストール

sudo -u www-data php artisan bookstack:install-module https://www.bookstackapp.com/hack-modules/mermaid-viewer.zip

途中で

Are you sure you trust this source?

と聞かれるのでyesで返答します。テーマが無い場合は

No active theme folder found...

と表示されるので同様にyesで返答します。

すると

themes/custom/

ディレクトリが作成され、

themes/custom/modules/mermaid-viewer/

ディレクトリへモジュールがインストールされます。

.env にテーマを設定（重要）

ここが今回ハマったポイントです。

.env を編集します。（要管理者/bookstack実行ユーザー権限）

APP_THEME=custom

を追加します。

これを設定しないと、themes/custom以下のディレクトリはは一切読み込まれません。

設定反映

php artisan optimize:clear

または

php artisan cache:clear
php artisan config:clear
php artisan view:clear

でキャッシュをクリアします。

（推奨）PHP/Apacheを再起動

PHP-FPMなら

sudo systemctl restart php8.3-fpm

Mod-PHP環境なら

sudo systemctl restart apache2

で、実行環境を再起動します。

設定反映確認

BookStackにログインして、設定反映されていることを確認します。

エディタの形式をMarkdownなら

```mermaid
flowchart TD
    A --> B
    B --> C
```
flowchart TD A --> B B --> C

保存後、閲覧画面でMermaid図としてレンダリングされます。

※ 編集画面の右ペインには表示されないのでご注意ください。

補足

インストール後のディレクトリは概ね以下のようになります。

BookStack/
└── themes/
    └── custom/
        └── modules/
            └── mermaid-viewer/

今回のポイント

実は一番重要なのはこのメッセージでした。

You will need to set APP_THEME=custom in your BookStack env configuration to enable this theme!

初回インストール時に表示されるのですが、見落としやすい一文です。

筆者も最初は「インストールは成功しているのに表示されない」という状況から別の原因を疑いましたが、このメッセージと APP_THEME の未設定を確認したことで、原因を特定できました。