Configuration Reference

The following reference covers all supported configuration options in the astro-lilypond integration.

import { defineConfig } from 'astro/config';
import lilypond from 'astro-lilypond';

export default defineConfig({
  integrations: [
    lilypond({
      // your configuration options here...
    }),
  ],
});

Top-level options

`format`

Type: "svg" | "png"
Default: "svg"

The output format passed to the LilyPond binary. Controls how the rendered output is embedded in the page.

lilypond({
  format: "png"
})

`defaults`

Type: object

Default settings applied when rendering each score. An individual .ly file can override defaults with its own settings.

`defaults.crop`

Type: boolean | "markdown-only"
Default: "markdown-only"

When cropped, margins are removed and the page is cropped to fit the rendered staves, producing a single image. When not cropped, the full page (or pages, for a multi-page score) is preserved.

"markdown-only" (default) crops Markdown fences, but leaves <LilyPond> components full-page.
true crops everywhere.
false never crops by default.

A <LilyPond> .ly import can always override this per-instance with ?crop or ?nocrop — see the component guide.

`defaults.cropScale`

Type: number
Default: 1.5

Multiplies the width/height set on a cropped score’s <img> tag, to compensate for LilyPond’s internal size units (points/mm) appearing too small once converted to pixels. Only affects the <img> dimensions on the page — the rendered file itself is unchanged, and this has no effect on uncropped (paginated) output.

lilypond({
  defaults: {
    cropScale: 2
  }
})

`defaults.resolution`

Type: number
Default: 144

Resolution to render .png files, in DPI. Only applies when format is set to png.

`defaults.version`

Type: string of the shape "2.<number>.<number>"
Default: "2.26.0"

To know how to output text, LilyPond needs to know a version to use for compilation. This is usually defined at the start of each .ly file:

```lilypond
  \version "2.26.0"
  \relative c' { c4 d e f }
```

By default, astro-lilypond will prepend this version for you, so you don’t need to write it yourself, which is helpful if you are writing a lot of small, inline music examples.

To pin your examples to a different default release, specify version:

lilypond({
  defaults: {
    version: "2.27.1" // Use the development release
  }
})

Blocks with an explicit \version declaration always use that version, regardless of the global config.

Information about the latest releases can be found on the LilyPond news page.