View on GitHub

quartz-transformer-mmlabc

quartz-transformer-mmlabc

quartz-transformer-mmlabc

コード進行をコードブロックに書くだけで、五線譜を表示してクリック演奏も可能にするQuartzトランスフォーマープラグイン。MML（Music Macro Language）とABC Notationも利用可

Japanese English Ask DeepWiki

※このドキュメントの一部はAI生成です

| 項目 | リンク | |——|——–| | 📊 開発状況 | generated-docs/development-status |

状況

3行で説明

機能

インストール

Quartzをインストールしたディレクトリにて以下を実行してください

npm install github:cat2151/quartz-transformer-mmlabc; pushd node_modules/quartz-transformer-mmlabc; npm run build; popd

この手順が必要な理由：

さらに、.github\workflows\deploy.yml の Build Quartzの前に、以下を追加してください

      - name: Build quartz-transformer-mmlabc
        run: npm run build
        working-directory: node_modules/quartz-transformer-mmlabc

この手順が必要な理由：

プラグインの更新方法（2つの選択肢）

重要: このプラグインは現在 Work In Progress であり、頻繁に破壊的変更が行われる可能性があります（nonstable）。プラグインの更新方法として、以下の2つの選択肢があります：

選択肢1: デプロイ時に常に最新版を使用する（推奨：開発中）

デプロイのたびに最新版のプラグインを使用したい場合は、.github/workflows/deploy.yml に以下のステップを追加してください：

      - name: Install Dependencies
        run: npm ci
      - name: Update quartz-transformer-mmlabc to latest
        run: npm update quartz-transformer-mmlabc
      - name: Build quartz-transformer-mmlabc
        run: npm run build
        working-directory: node_modules/quartz-transformer-mmlabc

メリット:

デメリット:

選択肢2: Dependabotによる週次更新に任せる

Dependabotを設定している場合、週次で自動的にプラグインの更新PRが作成されます。この方法では、更新内容を確認してからマージできます。

.github/dependabot.yml の例：

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"

メリット:

デメリット:

使い方

Quartz設定での使用

quartz.config.tsにトランスフォーマーを追加します：

import { QuartzConfig } from "./quartz/cfg"
import * as Plugin from "./quartz/plugins"
import { MMLABCTransformer } from "quartz-transformer-mmlabc"

const config: QuartzConfig = {
  configuration: {
    // ... サイト設定
  },
  plugins: {
    transformers: [
      Plugin.FrontMatter(),
      Plugin.CreatedModifiedDate({ priority: ["frontmatter", "filesystem"] }),
      // MMLABCトランスフォーマーを追加
      MMLABCTransformer(),
      // ... 他のトランスフォーマー
    ],
    filters: [Plugin.RemoveDrafts()],
    emitters: [
      Plugin.AliasRedirects(),
      Plugin.ComponentResources(),
      Plugin.ContentPage(),
      // ... 他のエミッター
    ],
  },
}

export default config

重要なポイント:

Markdownファイルでの使用

MML記法

```mml
t120 l4 cdefgab<c
```

コード進行記法

```chord
C Dm7 G7 C
```

ABC記法（直接指定）

```abc
X:1
T:Simple Scale
M:4/4
L:1/4
K:C
C D E F|G A B c|
```

トラブルシューティングや、ABC記法を直接記述したい場合に便利です。

オプション

プラグインはオプションの設定を受け付けます：

MMLABCTransformer({
  enableMML: true,    // MMLブロック変換を有効化（デフォルト: true）
  enableChord: true,  // コード進行ブロック変換を有効化（デフォルト: true）
  enableABC: true,    // ABCブロック変換を有効化（デフォルト: true）
})

仕組み

  1. プラグインはQuartzのビルドプロセス中にmml、chord、またはabc言語タグを持つコードブロックを検出
  2. これらのコードブロックを、ソース記法をデータ属性として含むHTMLのdiv要素に置き換え
  3. ブラウザ内で：
    • CDNからabcjsとmml2abcを読み込み
    • MMLブロックの場合：mml2abcを使用してMMLをABC記法に変換
    • コード進行ブロックの場合：chord2mmlを使用してコード進行をMMLに変換してからABC記法に変換
    • ABCブロックの場合：変換せずに記法を直接使用
    • abcjsを使用してABC記法をインタラクティブなSVGとしてレンダリング
    • オーディオシンセサイザーを初期化して楽曲の再生に対応
    • 楽譜をクリックして音楽を再生できるようにクリックイベントハンドラーを追加

Quartz v4 SPAナビゲーション対応

このプラグインはQuartz v4のSPA（Single Page Application）ナビゲーションに完全対応しています：

これにより、初回アクセス時だけでなく、他のページから楽譜を含むページに遷移した際も確実にレンダリングされます（Issue #63の修正）。

注意事項

テスト

プラグインには、包括的な自動テストスイートが含まれています：

テストの実行

# ユニットテストを1回実行
npm test

# インテグレーションテスト（Playwright）を実行
npm run test:integration

# 全テストを実行
npm run test:all

# ウォッチモードでテストを実行
npm run test:watch

# UIでテストを実行
npm run test:ui

テストカバレッジ

テストスイートには以下が含まれます：

手動テストには、同梱のdemo.htmlファイルを使用してください。

注意: Coding AgentがLinux Runnerでテストを行う際には、CDNがブロックされるため五線譜の表示が行われません。五線譜の表示を確認したい場合は、実機（ローカル環境）でテストしてください。

依存関係

ランタイム（CDN経由で読み込み）

重要: 以下のライブラリバージョンは、@cat2151 によりeasychord2mmlでの動作確認に基づいて指定されています。これらのURLを変更しないでください。

ビルド時

開発

ビルド

npm run build

プロジェクト構造

quartz-transformer-mmlabc/
├── src/
│   ├── index.ts          # メインプラグイン実装
│   └── index.test.ts     # ユニットテスト
├── test/
│   └── integration.test.ts # インテグレーションテスト
├── dist/                 # コンパイル出力（生成）
│   ├── index.js
│   └── index.d.ts
├── demo.html             # 手動テスト用デモファイル
├── package.json
├── tsconfig.json
├── vitest.config.ts      # Vitestテスト設定
├── playwright.config.ts  # Playwrightテスト設定
└── README.md

外部パッケージ方式を採用した理由

このプラグインは、Quartz本体に組み込む方式ではなく、外部npmパッケージとして配布する方式を採用しています。この設計判断には以下の理由があります：

  1. 再利用性
    • 複数のQuartzプロジェクトで同じプラグインを使用できます
    • 各プロジェクトでコードをコピーする必要がありません
  2. 独立性
    • プラグイン独自のリリースサイクルとバージョン管理が可能です
    • Quartz本体の更新に影響されずに開発・更新できます
  3. 共有性
    • GitHubを通じてコミュニティと簡単に共有できます
    • オープンソースプロジェクトとして多くのユーザーに使ってもらいやすくなります

この方式により、プラグインの価値を最大化し、より広いユーザーベースに対応できるようになっています。

ライセンス

MIT License - 詳細はLICENSEファイルを参照してください

関連プロジェクト

※英語版README.mdは、README.ja.mdを元にGeminiの翻訳でGitHub Actionsにより自動生成しています