View on GitHub

quartz-transformer-mmlabc

quartz-transformer-mmlabc

quartz-transformer-mmlabc

A Quartz transformer plugin that allows you to display sheet music and enable click-to-play functionality by simply writing chord progressions in a code block. MML (Music Macro Language) and ABC Notation are also available.

Japanese English Ask DeepWiki

※Some parts of this document are AI-generated.

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

Status

In 3 Lines

Features

Installation

Please run the following in your Quartz installation directory:

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

Reason for this step:

Additionally, before Build Quartz in .github\workflows\deploy.yml, please add the following:

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

Reason for this step:

How to Update the Plugin (2 Options)

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

If you want to use the latest version of the plugin with each deployment, please 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
      - name: Build quartz-transformer-mmlabc
        run: npm run build
        working-directory: node_modules/quartz-transformer-mmlabc

Pros:

Cons:

Option 2: Rely on Weekly Updates via Dependabot

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

Example .github/dependabot.yml:

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

Pros:

Cons:

Usage

Usage 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 settings
  },
  plugins: {
    transformers: [
      Plugin.FrontMatter(),
      Plugin.CreatedModifiedDate({ priority: ["frontmatter", "filesystem"] }),
      // Add the MMLABC transformer
      MMLABCTransformer(),
      // ... other transformers
    ],
    filters: [Plugin.RemoveDrafts()],
    emitters: [
      Plugin.AliasRedirects(),
      Plugin.ComponentResources(),
      Plugin.ContentPage(),
      // ... other emitters
    ],
  },
}

export default config

Important points:

Usage 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 conversion (default: true)
  enableChord: true,  // Enable chord progression block conversion (default: true)
  enableABC: true,    // Enable ABC block conversion (default: true)
})

How it Works

  1. The plugin detects code blocks with mml, chord, or abc language tags during the Quartz build process.
  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 a CDN.
    • For MML blocks: Converts MML to ABC Notation using mml2abc.
    • For chord progression blocks: Converts chord progressions to MML using chord2mml, then to ABC Notation.
    • For ABC blocks: Uses the notation directly without conversion.
    • Renders ABC Notation as interactive SVG using abcjs.
    • Initializes an audio synthesizer to support music playback.
    • Adds a click event handler to allow playing music by clicking the sheet music.

Quartz v4 SPA Navigation Support

This plugin is fully compatible with Quartz v4’s SPA (Single Page Application) navigation:

This ensures that sheet music is rendered not only on initial access but also when navigating to a page containing 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:testall

# 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, please use the included demo.html file.

Note: When a Coding Agent runs tests on a Linux Runner, CDN access may be blocked, preventing sheet music from being displayed. If you want 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 verified operation with easychord2mml by @cat2151. Please 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

Reason for Adopting an External Package Approach

This plugin adopts a method of distribution as an external npm package, rather than being embedded within the Quartz core. This design decision is based on the following reasons:

  1. Reusability
    • The same plugin can be used across multiple Quartz projects.
    • No need to copy code into each project.
  2. Independence
    • The plugin can have its own release cycle and version management.
    • Development and updates can occur independently of Quartz core updates.
  3. Shareability
    • Easily shareable with the community via GitHub.
    • Increases adoption by 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 the LICENSE file for details.

※This English README.md is automatically generated from README.ja.md by GitHub Actions using Gemini’s translation.