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, first create a directory for your .tmpl files, and then provide the --html-templates flag when building your docs:

booklit -i ./index.any -o ./docs \
    --html-templates ./html

3.1 Base Templates

The following template files will be executed if present under ./html, 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

Templates are executed 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

{{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

In addition to the above templates, using booklit.Styled will result in the renderer using the template named after the style being executed with the content being styled as .Content.

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

booklit.Styled{
  Style:   booklit.StyleBold,

  Content: content,
}

...where booklit.StyleBold is a const whose value is "bold", but could just as easily be any other string.

Booklit's base templates then include a bold.tmpl template:

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

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

3.3.1 Styles with Partials

Additional bits of content can be propagated to the template by setting them as 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

Sections can set their own style by invoking \styled with the name of a template. For the HTML renderer, this name corresponds to the template files (name).tmpl and/or (name)-page.tmpl under the given templates path.

This behaves very similarly to booklit.Styled, except the section can set it directly on itself, rather than being used for content generated by plugins.

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.

For a toplevel section, (name)-page.tmpl will be used if present. This overrides the default page.tmpl.