Introduction

Bard is a command-line tool that generates songbooks from Markdown sources.

In this book, you should find information on how to:

• Install Bard
• Setup a new project
• Write songs using Markdown

… and more.

Example

Check out the example songbook to get a feel for what the output looks like:

PDF

HTML

The sources for the example project can be found here.

About The Project

The purpose of Bard is to make it quick & easy to create songbooks for people to sing & play from around campfires, in jam sessions and similar. It is a non-profit open-source project.

The source code is licensed under the Apache 2.0 License (TL;DR). The default fonts used are Droid and Noto, under the Apache license.

Development happens in the open at GitHub.

Contributors

Bard was created by Vojtěch Král with inspiration and help from .

Code contributors:

Many thanks to the wonderful community at TeX Stack Exchange for always being there to help out with TeX issues.

Website front image by Joris Voeten.

Installation

Binary packages are provided for Linux and MS Windows on x86-64.
On other platforms or architectures, you can build from sources.

Linux

The following are provided:

• Static binary
• Deb package
• RPM package
• AUR package, AUR binary package
• Docker: vojtechkral/bard

To build PDFs, a TeX distribution is needed. Please consult your distribution package repository for the appropriate package. The default Bard template typically requires an extended TeXLive package such as texlive-xetex on Ubuntu, texlive-latexextra on Arch or texlive-scheme-medium on Fedora.

Alternatively, you can install the Tectonic engine.

See the TeX Configuration chapter for how to configure TeX use.

MS Windows

The following are provided:

• Portable binary
• Portable binary without Tectonic

The portable binary linked above contains the Tectonic TeX system, so no additional software is needed. If you’d like to use a different TeX system, such as MiKTeX, the Tectonic-less binary is recommended.

See the TeX Configuration chapter for how to configure TeX use.

From Sources

You will first need the Rust toolchain to build from sources – it can be installed via Rustup or from your OS package repository, if available.

Once the Rust toolchain is installed, i.e., the rustc and cargo commands are available, use the following command to build and install from sources using cargo:

cargo install -f bard

Project Setup

To start a new songbook, navigate to an empty directory with your command line and run:

bard init

This will initialize a new Bard project.

A Bard project is configured with a file named bard.toml in the root of the folder, written in the TOML format.

Apart from the bard.toml file, the project folder contains these subfolders:

• songs: Contains Markdown songs files.
• output: Outputs will be placed here.

Let’s go through the bard.toml file.

Inputs

The top of the file specifies the Bard version number and inputs:

version = 2

songs = [
    "yippie.md",
]

notation = "english"

The songs field is an array of filenames in the songs directory from which Bard loads the songs. It may also contain globs (filenames with wildcards) or be just one glob – to load all the .md files from songs in bulk, set it as:

songs = "*.md"

The songs are added in the songbook in the same order as they are defined in the songs field. By reordering the song files in the songs field, you control their order in the final output. Files matched by globs are ordered alphabetically.

The notation field defines the language-specific variant of chords used in the songs. This is only important if you use transposition, see the Transposition and Notation chapter for details.

Outputs

The outputs array defines what output files should be generated:

[[output]]
file = "songbook.pdf"

[[output]]
file = "songbook.html"

The default configuration lists two outputs: a PDF file and an HTML file.

ToC order

By default, the table of contents in both HTML and PDF outputs follows the same order in which the songs are specified in inputs.

To have the ToC sorted alphabetically, use the toc_sort setting. For example:

[[output]]
file = "songbook.pdf"
toc_sort = true

Book metadata

The final section describes the book:

[book]
title = "My Songbook"
subtitle = "(You can edit that title!)"
chorus_label = "Ch"
title_note = "(And this note too...)"

Here you can configure the book’s main title, its subtitle (optional), the label to be used for choruses, and a ‘title note’, which is a small piece of text on the bottom of the title page (optional).

See the bard.toml reference for the complete list of options.

Building the book and next steps

To build the project, use the following command:

bard make

If everything went well, you should see a PDF and an HTML file in the output directory.

Once you are happy with how the project is set up, you’ll probably want to start Writing Songs.

Writing Songs

Typically a song source looks something like this:

# Wild Mountain Thyme
## Irish & Scottish traditional

1. O the `G`summer `C`time `G`has come
And the `C`trees are sweetly `G`bloomin'
And the `C`wild `G`mountain `Em`thyme
Grows `C`around the `Am`bloomin' `C`heather
Will ye `G`go `C`lassie `G`go?

The header # Wild Mountain Thyme is the title of the song. All content following the header is considered part of that song until either the end of the file or a new H1 title (there may be multiple songs in one file).

The ## Irish & Scottish traditional is a subtitle. In the output, it appears underneath the main title in a smaller font. This is optional. There may also be several subtitles.

Lyrics and Chords

After the title, the first verse follows:

1. O the `G`summer `C`time `G`has come
And the `C`trees are sweetly `G`bloomin'
...

The chords are delimited with backticks (`) and inline within the lyrics. In the output, each chord will appear exactly above the text that follows it. Chords may be placed anywhere within the lyrics, including in the middle of a word or above a space or punctuation.

A chord span may contain multiple chords separated by spaces or other punctuation.

Chords may also be delimited with double backticks like this:

`G7`Oh Danny `C`Boy, the pipes, the ``C7``pipes are `F`calling

This indicates that the chord can be skipped if the player has trouble playing it. It is rendered in a thinner font in the output:

Finally, chords can be placed on the baseline of the text next to lyrics rather than above them. This is done by appending an underscore (_) after a chord or between several chords:

Baseline `C_D` chords.

This can be useful when writing chords for instrumental parts such as intros, solos or similar. See also the custom verse type below.

Paragraphs and whitespace

The lyrics can be divided into multiple paragraphs as part of one verse using a blank line.

Unlike in regular Markdown, line breaks are preserved – they are the same in the output as in the input. The text isn’t automatically wrapped.

Punctuation

By default, some punctuation such as ', ", or ... is converted to Unicode characters in a ‘smart’ way (e.g., pairing up quotes). For example, 'Hello' "world" ... is rendered as ‘Hello’ “world” ….

This can be turned off in bard.toml top section using:

smart_punctuation = false

Verses

The 1. in the above lyrics starts the first verse. Technically this is a Markdown ordered list. Just like in Markdown, the numbers don’t need to ascend in the correct order. In fact, you can number every verse as 1. and they will be correctly numbered in the output.

Numbered verses are considered “regular” verses. There are two more verse types.

Choruses

A chorus is started using the > syntax. This is the Markdown block quote element. For example:

> And we'll `C`all go `G`together to pull `C`wild `G`mountain `Em`thyme
All `C`around the `Am`bloomin' `C`heather, will ye `G`go `C`lassie `G`go?

The label used for choruses in the output is configured with the chorus_label property in the [book] section of bard.toml. The default chorus label is “Ch”. The above renders as:

If a song contains more than one chorus, use the >> syntax to start the second one, >>> for the third, etc.

Choruses can be referenced from anywhere in text using the !> extension syntax. The !> mark is replaced with chorus_label when rendering. !> references the first chorus, !>> the second one, etc. For example:

Will ye go lassie go? !>

will render as:

Special verses

Finally, a verse can be labelled with any label of your choosing using the H3 syntax:

### Intro
`Am_F_C_F_C_G`

or:

### Bridge
\
`F`Dance to the whistle, to the `Am`play, to the story
`G`To infinite en`D`cores
`F`Laugh at the royalty `C`with sad crowns
And re`G`peat the `Em`chorus once `Am`more...

The \ on a line is used to add a new line after the verse title. By default, the lyrics follow on the same line as the title.

Other Markdown Elements

These rich text Markdown elements are supported:

• Italics,
• bold text, and
• hyperlinks.

However, these are only supported in paragraph text, not in other elements such as headings.

These additional block Markdown elements are supported:

• Bullet lists,
• horizontal rules, and
• preformatted text blocks.

However, only flat structure is supported – nested lists are ignored.

Bard does not support inline HTML in Markdown. At least not as such; inline HTML is instead used for syntax extensions.

Markdown Standard

Except for the limitations and extensions listed above, Bard interprets Markdown according to the CommonMark standard.

Notation and Transposition

For the purpose of transposition, Bard supports these four notation systems:

• English
• German
• Nashville
• Roman (the same as Nashville except using Roman numerals)

The English notation is the default. If you live in, for example, central Europe or Scandinavia, you may want to set notation = "german" in your bard.toml.

However, if you don’t use transposition features, you don’t need to worry about this; Bard will simply use whatever you enter as chords. Correct notation setting is only needed when using transposition so that Bard can understand the chords you are using.

Transposition

To transpose your chords, use the !±X syntax, where X is the number of halftones. The chords will be transposed from that point onward. For example:

# Danny Boy

!+5

1. `G7`Oh Danny `C`Boy, the pipes, the ``C7``pipes are `F`calling

will shift the chords up by 5 halftones, aka perfect fourth:

If needed, use !+0 to go back to the original scale.

Second Set of Chords

Bard can also generate a second line of chords as a transposition of the first one. Use the !!±X syntax to generate a second row. The second row is, by default, rendered in blue font. For example:

# Danny Boy

!!+5

1. `G7`Oh Danny `C`Boy, the pipes, the ``C7``pipes are `F`calling

renders as:

Notation Conversion

Besides transposition, the notation system of chords can also be converted using the !notation syntax, where notation is one of the names listed above in lowercase.

This can be used just like transposition (and together with it) as well as for the second line of chords.

A comprehensive example of transposition and notation conversion to generate a ‘scale agnostic’ second line:

# Wild Mountain Thyme

!!-7
!!roman

1. O the `G`summer `C`time `G`has come
And the `C`trees are sweetly `G`bloomin'
And the `C`wild `G`mountain `Em`thyme

Fonts

Bard brings along the default font files so that output is rendered consistently on all systems.

The font files are stored in the output/fonts directory. These files are used by TeX when generating PDF files, but once the PDF file is generated, it no longer needs to refer to the fonts directory – you can distribute just the PDF file.

The HTML output, on the other hand, links to these files, so it is needed to distribute the fonts directory along with the HTML file, such as when uploading it onto the web.

By default, the Droid Serif font is used to display all text except chords and Noto Sans is used to display chords so that they are more distinguished from lyrics.

Using sans font everywhere

To use sans font for everything, use the sans_font setting in the output section in bard.toml:

[[output]]
file = "songbook.pdf"
sans_font = true

This works for the HTML output as well.

PDF font size

The default TeX template uses the 12pt font size. To use a different size, configure the font_size variable in the output section in bard.toml:

[[output]]
file = "songbook.pdf"
font_size = 11

This only applies to the PDF output. Please note that TeX classes usually support only specific font sizes. The default template supports the following sizes: 9, 10, 11, 12, 14, 17, 20, 25, 30, 36, 48, and 60.

The HTML file doesn’t set a specific font size and instead relies on the default font size used by the browser.

Images

The Markdown image element is supported in Bard. The image path is relative to the output directory. For example, if we put a file named horses.jpg in the output directory, we can use it like this:

1. `Am`Yippie yea `C`oh! ![horses](./horses.jpg) Yippie yea `Am`yay!

to get an output like this:

By default, the image renders inline within the text at the position of the image element.

Please note that while Bard supports displaying images, the flexibility of features will never be as good as with hand-crafted documents. There are limitations imposed by Markdown as well as output formats.

Centred and floating images

Markdown allows an additional parameter, a ‘title’, to be specified after the image path in double quotes. In Bard, this parameter is used to specify image position class. The syntax is as follows:

![image](./image.jpg "class")

Two classes are supported by Bard’s default templates:

• "center": the image is centred on the page with text above and below, and
• "right": the image floats on the right side of the page with text flowing left to it.

From the example project:

>> And I shall hear, though soft you tread above me
And all my dreams will warm and sweeter be
If you’ll not fail to tell me that you love me
I’ll sleep in peace until you come to me.

![hills](hills.jpg "center")

renders as:

and

2. I will build my love a bower
By yon cool crystal fountain ![thyme](thyme.png "right")
And round it I will pile
All the wild flowers o' the mountain.
Will ye go lassie go? !>

(...)

renders as:

DPI settings

In PDF, the DPI setting governs the relationship between image size in pixels and its physical size when printed. DPI is configured with the dpi property in the output section. Its value is a numeral in units of pixels per inch.
The default is 144 pixels per inch.

In HTML, there is no concept of DPI as such; instead, the dpi field is used as a scaling factor by which the image dimensions are multiplied when HTML image elements are rendered – for example, the value of 0.5 would halve the dimensions.
The default is 1.0, i.e., no scaling applied.

Example of custom DPI settings:

[[output]]
file = "songbook.pdf"
dpi = 192

[[output]]
file = "songbook.html"
dpi = 0.75

TeX Configuration

The T_EX typesetting system is used to render PDFs. Currently, Bard supports the XeLaTeX and Tectonic implementations. By default, Bard attempts to use one of these by searching for the xelatex and tectonic binary in that order.

Additionally, the Windows binary embeds the Tectonic software inside, so it doesn’t need a TeX distribution to be installed on the system. However, it still performs the lookup so that if a XeLaTeX or Tectonic distro is installed, it will be preferred over the embedded one.

The automatic lookup can be overridden in two ways:

• Using the BARD_TEX environment variable.
• Using the tex option in bard.toml top-level section.

If both are used, the BARD_TEX variable takes precedence.

The syntax for both is:

distro_type

or

distro_type:path

The distro_type can be xelatex, tectonic, or none (see below). On Windows, it may also be tectonic-embedded to force the usage of embedded Tectonic.

Optionally, a path to a specific binary may be specified after the :.

Examples

On the command line via the BARD_TEX variable:

BARD_TEX=tectonic bard make

– use Tectonic, look up the tectonic binary in $PATH.

BARD_TEX=tectonic:/opt/tectonic/bin/tectonic bard make

– use a Tectonic binary at /opt/tectonic/bin/tectonic.

Using bard.toml:

tex="xelatex:C:\\Programs\\TeX\\xelatex.exe"

– use a XeLaTeX binary at C:\Programs\TeX\xelatex.exe.

Number of TeX passes

By default, Bard runs three passes of the TeX engine to ensure page numbers are correctly computed.

To adjust this amount, modify the tex_runs variable in the relevant [[output]] section. For example, to only run TeX once:

[[output]]
file = "songbook.pdf"
tex_runs = 1

Preserving TeX files

The TeX file, as well as temporary files produced by TeX, are automatically removed by Bard.

To keep them, use bard make -k to keep the TeX file and bard make -kk to also keep the temporary TeX files.

Preventing running TeX

If you wish the TeX engine to not run at all, you can:

• use bard make -p,
• set BARD_TEX=none, or
• set tex=none in bard.toml

ToC sorting configuration

When sorted ToC is enabled, Bard modifies a TeX intermediate .toc file between TeX runs by sorting its lines with a regex. The built-in default regex should work with the default template and widely used TeX engines. If, however, the default doesn’t work or a custom template is used, the regex can be set using toc_sort_key:

[[output]]
file = "songbook.pdf"
toc_sort = true
toc_sort_key = "numberline\\s+\\{[^}]*}([^}]+)"

The regex must contain a capture group, i.e., (...), which is the sorting key.

Templates

Bard uses Handlebars templates to render HTML files and PDF files through TeX. This is, by default, invisible to the user, but the templates are entirely customizable.

To obtain the default template for an output, specify a template path in bard.toml:

[[output]]
file = "songbook.pdf"
template = "pdf.hbs"

[[output]]
file = "songbook.html"
template = "html.hbs"

… and then run bard make. Bard will create missing template files for PDF (TeX) and HTML formats with default content.

The AST

When rendering, Bard passes the entire songbook AST (abstract syntax tree) to a template in a few JSON objects. Most notable are the book and songs objects:

• book is a copy of the [book] section in bard.toml and contains the book’s main title, subtitle and other metadata.
• songs is an array of all the songs in the same order as loaded from the files. Each song object contains a title, subtitles (if any), and an array of blocks which make up the content of the song. There are several types of blocks, some of which may contain inlines. There are several types of inlines, such as chords, lyrics, etc.

As an example, you can refer to the AST for the example songbook. You can also export the AST of your songbook in JSON format – see the JSON and XML chapter. Finally, there is the all-features test project whose exported AST should contain all the possible elements.

The format of the AST is versioned to guard against incompatibilities. The AST will not change in an incompatible way between Bard releases of the same major number.

Because of this, Bard templates start with a version check call.

Basic Structure and Inline Partials

At the most basic level, the purpose of the template is to loop through the songs array and render each song. A very simple HTML template might look like this:

{{~ version_check "1.2.0" ~}}
<html>
<body>
  <h1>{{ book.title }}</h1>
  {{#if book.subtitle }}<h3>{{ book.subtitle }}</h3>{{/if }}

  {{#each songs}}
    <h2>{{ title }}</h2>

    <div>
      {{#each blocks}}{{> (lookup this "type") }}{{/each}}
    </div>
  {{/each}}
</body>
</html>

Rendering with this template will render a HTML file only containing song titles. To render the content, Bard templates make heavy use of Handlebars’ inline partials to define how various elements are displayed. The {{#each blocks}} ... {{/each}} syntax loops through the blocks of the current song. The {{> (lookup this "type") }} incantation reads the type field of the block and dispatches to a handlebars partial of that name.

The most important block type is the verse type, named b-verse (the b- prefix is for block). Let’s define a partial to render a verse:

{{#*inline "b-verse"}}
  <h3>
    {{~#with label}}
      {{~#if verse}}{{verse}}.{{/if}}
      {{~#if (contains this "chorus")}}{{@root.book.chorus_label}}{{chorus}}.{{/if}}
      {{~#if custom}}{{custom}}{{/if}}
    {{~/with~}}
  </h3>

  {{~#each paragraphs~}}
    {{#each this}}{{> (lookup this "type") }}{{/each}}
  {{~/each~}}
{{/inline}}

First, the verse label is rendered – there are three label types, each accounted for. Then, the code loops through paragraphs, which is an array of arrays of inlines. Each array of inlines is looped through with the {{#each this}}{{> (lookup this "type") }}{{/each}} line. Each inline is dispatched to a partial in the same way blocks are dispatched by reading the type field and calling a partial of that name.

We’re going to implement inlines i-text, i-break, and i-chord. The partials for i-text and i-break will be very simple:

{{#*inline "i-text"}}{{ text }}{{/inline}}
{{#*inline "i-break"}}<br>{{/inline}}

The partial for i-chord:

{{#*inline "i-chord"~}}
<table style="display: inline-table; vertical-align: bottom; border-collapse: collapse;">
  <tr><td style="color: red">{{ chord }}</td></tr>
  <tr><td>{{#each inlines}}{{> (lookup this "type") }}{{/each}}</td></tr>
</table>
{{~/inline}}

The chord again contains inlines in a recursive way (although it is guaranteed never to contain another chord). This way, the text within an i-chord type will be dispatched to the i-text inline, just like from b-verse.

With these in place, a very basic template should be complete. You can download the whole source code. The template won’t render some finer features such as bold text, italics, alt chords, images etc., but will render basic song content:

Escaping and whitespace

Songbook textual content is escaped such that it doesn’t contain characters with special meaning in HTML and TeX, such as < or > in HTML and % or $ in TeX.

TeX, in particular, is very sensitive to whitespace, which is why whitespace control is used often in the PDF template – many Handlebars elements are prefixed and/or suffixed with ~ to remove leading/trailing whitespace.

A particularly troublesome case is when you need to wrap a variable in a TeX command like this:

\foo{{{variable}}}

This will fail to render, as Handlebars will interpret that as a raw block. To get around this, use the following:

\foo{ {{~variable~}} }

Handlebars helpers

Bard provides a few utility helpers for use in templates – see the reference.

Upgrading

The built-in templates occasionally change in order to improve, add features, or fix bugs. Custom templates, however, are not upgraded, and there isn’t a feasible way to automatically apply improvements to them. The templates are fairly monolithic units.

Therefore, unfortunately, upgrading of custom templates has to be done manually.
The git history of the PDF and HTML templates can be used to see what recently changed in the default templates.

Custom Extensions

Bard Markdown syntax can be extended using “HTML” code. Since inline HTML code is otherwise unused (it would not be very useful in TeX/PDF output), it is repurposed as a way to call into user-defined extensions.

For example, in the following Markdown:

# Song

1. <foo>example</foo>.

In the AST, the tag pair is represented by inlines of type i-tag. The tag name is prefixed with h- and dispatched to an inline partial of that name. For the closing tag, the slash / is included in the name. So, in this example, first, a partial named h-foo is called, then the text example is rendered, and then a partial named h-/foo is called. Since, by default, the two partials h-foo and h-/foo don’t exist, the tags don’t do anything; only example will be rendered. However, you can define those two partials in your template.

“HTML” tags may also enclose whole blocks of text like so:

<foo>

1. O the `G`summer `C`time `G`has come
And the `C`trees are sweetly `G`bloomin'...

</foo>

In this example, it is important that there is a newline between the opening tag (<foo>) and the following block. Due to Markdown parsing rules, if the block follows without a newline, it is considered part of the HTML code and not parsed as Markdown (Bard warns you if this happens).

Example: Font size

Suppose we want an extension to render a part of the lyrics in a smaller font. We’ll name it small and use it like this:

# Song

1. Normal text size.
<small>This should be in a smaller font...</small>

To make this work, two partial inlines need to be added to the TeX template:

{{#*inline "h-small"}}\small{}{{/inline}}
{{#*inline "h-/small"}}\normalsize{}{{/inline}}

And in the HTML template, they will be defined as:

{{#*inline "h-small"}}<small>{{/inline}}
{{#*inline "h-/small"}}</small>{{/inline}}

This will render the text a bit smaller in both the PDF and HTML output.

Attributes

It is possible to use HTML attributes to parametrize an extension. Every attribute defined on the HTML tag will be available in the h- inline as a Handlebars variable.

Example: Youtube embed

Let’s suppose we’d like to make it possible to embed a YouTube video in the HTML output. We’ll be adding links in the song sources like this:

<youtube id="zlfbhc3NBTA">

The id attribute references the YouTube video ID we’d like to link.

To make this work, we’ll add the following inline in the HTML template:

{{#*inline "h-youtube"}}
  <iframe src="https://www.youtube.com/embed/{{id}}" allowfullscreen frameborder="0"></iframe>
{{/inline}}

The {{id}} part renders the attribute id that we’ve passed in from Markdown.

In paper documents, video links are not very practical, so we won’t be defining an h-youtube inline in the TeX template. The element will simply be ignored in TeX.

JSON and XML Output

Besides the usual PDF and HTML format, Bard can also output songbook data in JSON and XML. This is primarily useful for template writing, debugging or further processing.

To get JSON and/or XML files, add them as additional outputs:

[[output]]
file = "songbook.json"

[[output]]
file = "songbook.xml"

The JSON data is the AST of the whole parsed songbook, and it is exactly the same as the data which gets passed to the rendering templates.

The XML data contains the same data semantically but is exported in a shape more suitable for this format. Warning: The XML format is somewhat experimental and is not covered by the backwards compatibility guarantee, unlike JSON.

Both formats are defined within the source code; formal schema definitions are not available.

Scripts

The script feature makes it possible to post-process Bard outputs arbitrarily with script files.

Scripts are defined per output. To configure, set the script option on the relevant output, for example:

[[output]]
file = "songbook.html"
script = "foo"

The script name is specified without the file extension. The extension is assumed automatically based on the operating system:

The script file should be placed in the output directory, and it is also executed in the output directory (i.e., with the current directory being set to the output directory).

Note: On Linux/Unix, the script .sh file should have the executable permission bit set so the user running Bard can also run the script file.

Environment variables

The following environment variables are set by Bard when running the script:

Example: All chords in the book

In this example, we’ll define a script that will export all the chords in the songbook as a JSON array. We’ll be using the jq program to do this.

First, let’s add a JSON output with a script file set:

[[output]]
file = "songbook.json"
script = "chords"

Then, we’ll create a file named chords.sh, set the exec bit (chmod 755 chords.sh), and write the following contents

#!/bin/sh

jq '[ .songs[].blocks[].paragraphs[][] | select(.type == "i-chord").chord ] | unique' "$OUTPUT" > "${OUTPUT_STEM}-chords.json"

After building the project, a file named songbook-chords.json should be generated in the output directory. It should contain a list similar to this:

[
  "Am",
  "C",
  "C7",
  "D",
  "D7",
  "Dm",
  "Em",
  "F",
  "G",
  "G7"
]

Zpěvník pro Android

Note: This section is in the Czech language as it is only relevant to users of a specific Czech-only Android app.

Bard umí generovat zpěvníky pro aplikaci Zpěvník p. Karla Hovorky.

Tyto zpěvníky jsou ve formátu XML a vytvoříme je přidáním dalšího výstupu ([[output]]) v souboru bard.toml. Aby se odlišily od obecného XML výstupu, je potřeba explicitně nastavit formát výstupu na hovorka. Například:

[[output]]
file = "songbook.hovorka.xml"
format = "hovorka"

Vygenerovaný soubor songbook.hovorka.xml následně můžeme zkopírovat do telefonu nebo tabletu s Androidem a importovat ho v aplikací Zpěvník.

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

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

notation = "english"

smart_punctuation = true

tex = "xelatex"

file = "songbook.pdf"

template = "pdf.hbs"

format = "pdf"

sans_font = false

font_size = 12

toc_sort = true

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

dpi = 144.0

tex_runs = 3

script = "postprocess"

book = { front_img = "guitar_pdf.jpg" }

title = "Bard Songbook"

subtitle = "An example project"

chorus_label = "Ch"

front_img = "guitar.jpg"

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

Migration to version 2

There were a few incompatible changes in Bard 2.x. To convert your project to Bard 2.x, perform the following updates:

bard.toml version

The bard.toml file now contains an explicit version field corresponding to the program’s major version. Add the following line at the top of the file:

version = 2

PDF format and post-processing

In bard 1.x, .tex files were generated and rendered as PDFs using the process field. This is now done by Bard automatically. The tex format is replaced by the pdf format, and the process field is no longer recognized.

To migrate a PDF [[output]]:

• Specify a file with a .pdf extension.
• If you used an explicit format field, change it to "pdf".
• Remove the process field. If you used the process field for a purpose other than TeX invocation, see Scripts.
• Optionally specify ToC sorting.

Fonts

The new default template now relies on the output/fonts directory containing font files. To obtain it, navigate to an empty directory and call bard init. Then you can copy the output/fonts directory to your existing project’s output directory.

Hovorka

The Hovorka format must now be explicitly defined to be distinguished from the general XML AST output. Add the following in the relevant [[output]]:

format = "hovorka"

Templates

If you are using the default template without changes, it is recommended to delete it as Bard now, by default, uses built-in templates without saving them to disk.

Templates have been changed significantly between the two major versions. If you used customizations, please refer to Templates - upgrading. The default templates can also be obtained by specifying a non-existing file in the output’s template field - the file will be generated with default template content.

Backmatter

The book.backmatter option in bard.toml is no longer recognized by the default templates. To customize backmatter, modify the relevant template itself.

HTML file extensions

Alternative HTML extension – .htm, .xhtml, and .xht – are no longer auto-detected, it is recommended to use .html.

Template helpers

This is a reference of Handlebars helpers, which Bard provides to templates.