3 The HTML Renderer

The presentation of your content is controlled by a renderer. At present, there is only one, and it's probably the one you'll want to use: HTML, for generating static websites.

Booklit comes with some extremely barebones templates that don't include any styling at all. You'll probably want to change that.

The HTML renderer uses Go's built-in html/template package. To override templates, create a directory for your .tmpl files and pass it to Booklit with the --html-templates flag.

The --html-templates flag must be passed every time you build your docs, so you may want to put it in a script:

#!/bin/bash

booklit -i lit/index.lit -o public \
  --html-templates ./html \
  "$@" # forward args from script to booklit

3.1 Base Templates

The following template files will be executed if present in the HTML templates directory, with the corresponding data type as .:

template	type for `.`
`page.tmpl`	`*booklit.Section`
`section.tmpl`	`*booklit.Section`
`link.tmpl`	`booklit.Link`
`list.tmpl`	`booklit.List`
`paragraph.tmpl`	`booklit.Paragraph`
`preformatted.tmpl`	`booklit.Preformatted`
`reference.tmpl`	`*booklit.Reference`
`sequence.tmpl`	`booklit.Sequence`
`string.tmpl`	`booklit.String`
`target.tmpl`	`booklit.Target`
`toc.tmpl`	`*booklit.Section`
`aside.tmpl`	`booklit.Aside`
`definitions.tmpl`	`booklit.Definitions`
`table.tmpl`	`booklit.Table`
`image.tmpl`	`booklit.Image`

The most impactful of these is page.tmpl, which is used for the top-level section for each "page" rendered. This is where you would place assets in <head>, for example.

3.2 Template Functions

Booklit executes templates with the following functions available:

{{tag | url}}: generate a URL for the tag
{{content | stripAux}}: strip \aux elements from the content
{{string | rawHTML}}: render the string as raw HTML, unescaped
{{string | rawURL}}: permit the rendered value to be placed in a url="" attribute
{{content | render}}: render the content
{{walkContext currentSection subSection}}: generate a convenience struct with fields .Current and .Section, useful for traversing a tree of sections while retaining the "current" section, e.g. so it can be marked as "active" in a navigation tree
{{section | headerDepth}}: return the number that should be used for the section's header, i.e. <hN>

3.3 Styled Content

Styled content, i.e. booklit.Styled, instructs the HTML renderer to use the *.tmpl template named after the style.

For example, \bold is implemented in the baselit plugin by returning:

booklit.Styled{
  Style:   booklit.StyleBold, // "bold"
  Content: content,
}

Booklit includes a bold.tmpl template which is evaluated with . as the booklit.Styled value:

<strong>{{.Content | render}}</strong>

Thus, when content is styled with "bold", it will render in strong tags.

3.3.1 Styles with Partials

Additional content can be propagated to the template by setting it Partials:

booklit.Styled{
  Style:   "my-wackadoo-style",
  Content: content,

  Partials: booklit.Partials{
    "Title": title,
  },
}

Then, with my-wackadoo-style.tmpl as the following:

<div class="wack">
  <h1>{{.Partial "Title" | render}}</h1>

  {{.Content | render}}
</div>

This would result with title rendered in between the <h1> tags, and content rendered below.

3.4 Styled Sections

Using \styled instructs the HTML renderer to use (name).tmpl instead of section.tmpl, or (name)-page.tmpl instead of page.tmpl (if it exists).

So, given the following example:

\title{Fancy Section}

\styled{fancy}

I'm a fancy section!

\section{
  \title{Sub-section}

  I'm a normal sub-section!
}

...and the following as fancy.tmpl under the given templates path (--html-templates):

<div class="fancy">
  <em><strong>{{.Title | render}}</strong></em>

  {{.Body | render}}

  {{if not .SplitSections}}
    {{range .Children}}
      {{. | render}}
    {{end}}
  {{end}}
</div>

...the following will be the rendered HTML for the section:

<div class="fancy">
  <em><strong>Fancy Section</strong></em>

  <p>I'm a fancy section!</p>

  <h2>Sub-section</h2>

  <p>I'm a normal sub-section!</p>
</div>

Note that the styling only applies to the section that declares it; it does not propagate to its children.