View on GitHub

quartz-transformer-mmlabc

quartz-transformer-mmlabc

quartz-transformer-mmlabc

A Quartz transformer plugin that allows you to display sheet music and play it by clicking, just by writing chord progressions in a code block. MML (Music Macro Language) and ABC Notation are also available.

Japanese English Ask DeepWiki

※Parts of this document are AI-generated

| Item | Link | |——|——–| | 📊 Development Status | generated-docs/development-status |

Status

In 3 Lines

Features

Installation

Run the following in your Quartz installation directory:

npm install github:cat2151/quartz-transformer-mmlabc

The plugin is installed directly from GitHub (not from npm). Since pre-built files (the dist directory) are included in the repository, it can be used immediately after installation.

Migration Guide for Existing Users

Important: Starting from this version, the dist folder is included in the repository, eliminating the need for manual builds.

Updating GitHub Actions Workflow

If you are already building the plugin with GitHub Actions, please remove the build step.

Before:

      - 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
      - name: Build Quartz
        run: npx quartz build

After:

      - name: Install Dependencies
        run: npm ci
      - name: Update quartz-transformer-mmlabc to latest
        run: npm update quartz-transformer-mmlabc
      - name: Build Quartz
        run: npx quartz build

Change: Remove the Build quartz-transformer-mmlabc step. This step is no longer necessary as pre-built files are included in the repository.

How to Update the Plugin (2 Options)

Important: This plugin is currently Work In Progress and may undergo frequent breaking changes (nonstable). There are two options for updating the plugin:

If you want to use the latest version of the plugin with each deployment, add the following steps to .github/workflows/deploy.yml:

      - name: Install Dependencies
        run: npm ci
      - name: Update quartz-transformer-mmlabc to latest
        run: npm update quartz-transformer-mmlabc

Pros:

Cons:

Option 2: Rely on weekly updates via Dependabot

If Dependabot is configured, it will automatically create weekly PRs for plugin updates. With this method, you can review the changes before merging.

Example .github/dependabot.yml:

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

Pros:

Cons:

Usage

Using in Quartz Configuration

Add the transformer to quartz.config.ts:

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

const config: QuartzConfig = {
  configuration: {
    // ... site configuration
  },
  plugins: {
    transformers: [
      Plugin.FrontMatter(),
      Plugin.CreatedModifiedDate({ priority: ["frontmatter", "filesystem"] }),
      // Add MMLABC transformer
      MMLABCTransformer(),
      // ... other transformers
    ],
    filters: [Plugin.RemoveDrafts()],
    emitters: [
      Plugin.AliasRedirects(),
      Plugin.ComponentResources(),
      Plugin.ContentPage(),
      // ... other emitters
    ],
  },
}

export default config

Key Points:

Using in Markdown Files

MML Notation

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

Chord Progression Notation

```chord
C Dm7 G7 C
```

ABC Notation (Direct Specification)

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

Useful for troubleshooting or when you want to write ABC Notation directly.

Options

The plugin accepts optional settings:

MMLABCTransformer({
  enableMML: true,    // Enable MML block transformation (default: true)
  enableChord: true,  // Enable chord progression block transformation (default: true)
  enableABC: true,    // Enable ABC block transformation (default: true)
})

How It Works

  1. During Quartz’s build process, the plugin detects code blocks with mml, chord, or abc language tags.
  2. These code blocks are replaced with HTML div elements containing the source notation as a data attribute.
  3. In the browser:
    • Loads abcjs and mml2abc from CDN.
    • For MML blocks: Uses mml2abc to convert MML to ABC Notation.
    • For chord progression blocks: Uses chord2mml to convert chord progressions to MML, then to ABC Notation.
    • For ABC blocks: Uses the notation directly without conversion.
    • Uses abcjs to render the ABC Notation as interactive SVG.
    • Initializes an audio synthesizer to support music playback.
    • Adds click event handlers to allow playing music by clicking the sheet music.

Quartz v4 SPA Navigation Support

This plugin fully supports Quartz v4’s SPA (Single Page Application) navigation:

This ensures that sheet music is rendered reliably not only on initial access but also when navigating to a page containing sheet music from other pages (fixes Issue #63).

Notes

Testing

The plugin includes a comprehensive automated test suite:

Running Tests

# Run unit tests once
npm test

# Run integration tests (Playwright)
npm run test:integration

# Run all tests
npm run test:all

# Run tests in watch mode
npm run test:watch

# Run tests with UI
npm run test:ui

Test Coverage

The test suite includes:

For manual testing, use the included demo.html file.

Note: When a Coding Agent runs tests on a Linux Runner, CDN access may be blocked, preventing the display of sheet music. To verify sheet music display, please test on a physical machine (local environment).

Dependencies

Runtime (Loaded via CDN)

Important: The following library versions are specified based on operational verification with easychord2mml by @cat2151. Do not change these URLs.

Build-time

Development

Build

npm run build

Project Structure

quartz-transformer-mmlabc/
├── src/
│   ├── index.ts          # Main plugin implementation
│   └── index.test.ts     # Unit tests
├── test/
│   └── integration.test.ts # Integration tests
├── dist/                 # Compiled output (generated)
│   ├── index.js
│   └── index.d.ts
├── demo.html             # Demo file for manual testing
├── package.json
├── tsconfig.json
├── vitest.config.ts      # Vitest test configuration
├── playwright.config.ts  # Playwright test configuration
└── README.md

Reasons for Adopting an External Package Approach

This plugin is distributed as an external npm package rather than being built into the Quartz core. The design decision was made for the following reasons:

  1. Reusability
    • The same plugin can be used across multiple Quartz projects.
    • Eliminates the need to copy code into each project.
  2. Independence
    • Allows for its own release cycle and version management.
    • Can be developed and updated independently of Quartz core updates.
  3. Shareability
    • Easily shareable with the community via GitHub.
    • Increases accessibility for a wider user base as an open-source project.

This approach maximizes the plugin’s value and caters to a broader user base.

License

MIT License - See LICENSE file for details

※The English README.md is automatically generated by GitHub Actions using Gemini’s translation based on README.ja.md.