bard.toml Reference

This is a list of fields recognized in the bard.toml settings file.
Most of the fields are optional; only a few are required; these are marked as such.

version = 2

Required. Major version of Bard this project was created with. Used for compatibility checks.

songs = "*.md"
# or
songs = [ "", "", "foo/*.md", "..." ]

Required. The input files specification. See Inputs.

notation = "english"

Chord notation used in the input files. Only needed for transposition. See Notation and Transposition.

smart_punctuation = true

Whether the Markdown parser should produce smart quotations and ellipsis. See Punctuation.

tex = "xelatex"

Specifies which TeX implementation should be used. See TeX configuration.


The output field is an array of tables. Each output may have the following fields:

file = "songbook.pdf"

Required. Output file name relative to the output directory.

template = "pdf.hbs"

Path to the template file for this output relative to the templates directory. (See also Templates.)

format = "pdf"

Output format. Possible choices: "pdf", "html", "hovorka", "json", or "xml". Usually, this isn’t required since the format is detected from the file’s extension.

sans_font = false

Whether a sans-serif font should be used in PDF and HTML outputs instead of the default serif font.

font_size = 12

Font size in PDF outputs. See PDF font size.

toc_sort = true

Whether the table of contents should be sorted alphabetically in PDF and HTML outputs. See ToC order.

toc_sort_key = "numberline\\s+\\{[^}]*}([^}]+)"

A customized ToC sort key extraction regex for PDF outputs. See ToC sorting configuration.

dpi = 144.0

For PDF outputs, this is the resolution of images in points per inch. For HTML outputs, this is the image scaling factor. See DPI settings.

tex_runs = 3

Number of TeX rendering passes when generating PDFs. See Number of TeX passes.

script = "postprocess"

Base name of a post-processing script file used for this output without the extension. See Scripts.

book = { front_img = "guitar_pdf.jpg" }

Override any field of the [book] section (see below) specifically for this output.


The book table describes basic metadata about your songbook; it is used by the rendering templates.

title = "Bard Songbook"

The main title of the songbook.

subtitle = "An example project"

Sub-title, shown on the title page as well, but in smaller font.

chorus_label = "Ch"

Label to be used for chorus verses without the dot.

front_img = "guitar.jpg"

An image shown on the title page.

title_note = "A set of a few non-copyrighted songs."

An additional note in small font on the bottom of the title page.