Configuration

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...
    }),
  ],
});

Options

`autoInstall`

Type: boolean | { version?: string }
Default: true

Download a prebuilt release of the lilypond binary when none is found on PATH.

To install a specific version, pass an object to pin the version downloaded:

lilypond({
  autoInstall: { version: "2.27.1" }
})

A lilypond installation already on PATH always takes priority over a downloaded one.

lilypond({
  // Only ever use a PATH install
  autoInstall: false
})

Downloads are cached per OS. The cache directory can be overridden with the ASTRO_LILYPOND_CACHE_DIR environment variable.

OS	Cache location
Linux	`$XDG_CACHE_HOME/astro-lilypond` (falls back to `~/.cache/astro-lilypond`)
macOS	`~/Library/Caches/astro-lilypond`
Windows	`%LOCALAPPDATA%\astro-lilypond\Cache`

`defaults`

Type: object

Default settings applied to every score.

`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.format`

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

The output format used for every score.

lilypond({
  defaults: {
    format: "png"
  }
})

Individual .ly/.ily imports and lilypondLoader() entries can override this per call via getScore()’s or <Score>’s own format option; Markdown fences always use this default.

`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
  }
})

LilyPond code with an explicit \version declaration will always use that version, regardless of the global default configured here.

`includePaths`

Type: string[]
Default: []

Extra directories LilyPond should search for files, in addition to each score’s own directory (which is always searched automatically). Relative paths resolve against the project root. This setting is useful if you store shared styles, layouts, and helper definitions separately from your main scores.

lilypond({
  includePaths: ["./src/snippets"],
})

Once configured, content from includePaths can be referenced elsewhere:

\include "my-snippet.ily"