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.