Booklit

the little static site engine that could

1 Getting Started

Getting started with Booklit assumes basic knowledge of the Go programming language. Be sure to have it installed!

The best way to get started with Booklit is to create a Go module with Booklit as a dependency:

# create go.mod and go.sum
go mod init example

# add booklit to go.mod and install CLI
go get github.com/vito/booklit/cmd/booklit

It's also possible to download the booklit executable from the latest GitHub release, but tracking it as a dependency will make it easier to write a plugin later on.

1.1 Hello, world!

First, create a file called hello.lit with the following content:

\title{Hello, world!}{hello}

I'm a Booklit document!

This file can exist anywhere, but one common convention is to place .lit documents under lit/, HTML templates under html/, and plugin code under go/.

Run the following to build and render the file to ./docs/hello.html:

$ booklit -i hello.lit -o docs

Each of the changes in the following sections will require re-building, which can be done by running the above command again. Alternatively, you can run booklit with the -s flag to start a HTTP server:

$ booklit -i hello.lit -s 8000
INFO[0000] listening              port=8000

Once Booklit says 'listening', browse to http://localhost:8000/hello.html. When you change anything, just refresh and your content will be rebuilt and re-rendered.

1.2 Organizing with Sections

Next, let's try adding a section within our document:

\title{Hello, world!}{hello}

I'm a Booklit document!

\section{
  \title{Hi there!}

  I'm so organized!
}

After building, you should see something like this:

Hello, world!

I'm a Booklit document!

1 Hi there!

I'm so organized!

That number "1" might look a bit weird at the moment, but it's the section number, and it'll be something like "3.2" for a nested section. You can always remove it by specifying your own template (more on that later), but for now let's leave it there.

1.3 Splitting Sections

To render each sub-section on its own page, simply call \split-sections somewhere in the section.

\title{Hello, world!}{hello}

\split-sections

I'm a Booklit document!

\section{
  \title{Hi there!}

  I'm so organized!
}

So far we've just made the section disappear, which isn't very helpful. Let's at least make it so we can browse to it! This can be done with \table-of-contents:

\title{Hello, world!}{hello}

\split-sections

I'm a Booklit document!

\table-of-contents

\section{
  \title{Hi there!}

  I'm so organized!
}

Note that when viewing the sub-section, its header is now a <h1> rather than the <h2> it was before, since it stands on its own page.

1.4 References & Tagging

Having a \table-of-contents is great and all, but more often you'll want to reference sections from each other directly and in context. This can be done with \reference:

\title{Hello, world!}{hello}

\split-sections

I'm a Booklit document! To read further, see \reference{hi-there}.

\section{
  \title{Hi there!}

  I'm so organized!
}

The first argument to \reference is the name of a tag to link. At build time, references will resolve to their tag and generate a link to it. By default, the name of the link is determined by the tag, so for a section it'll be the section's title. This can be overridden by passing a second argument to \reference:

\title{Hello, world!}{hello}

\split-sections

I'm a Booklit document! Consult \reference{hi-there}{this section} for
more.

\section{
  \title{Hi there!}

  I'm so organized!
}

1.5 Next Steps

What we've gone over should carry you pretty far. But you'll likely want to know a lot more.