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.