1 Getting Started

First you'll need to grab the booklit CLI. This can be fetched from the latest GitHub release. Download the appropriate binary for your platform, chmod +x it, and drop it somewhere in your $PATH.

The chmoding and copying can be done in one fell swoop with install, like so:

$ install ~/Downloads/booklit_* ~/bin/booklit

Then, run booklit -v. You should see the version number printed out, assuming ~/bin is in your $PATH.

1.1 Hello, world!

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

\title{Hello, world!}{hello}

I'm a Booklit document!

Then, run the following to build it as ./docs/hello.html:

$ booklit -i hello.lit -o docs

Each of the changes in the following sections will necessitate re-building. This can be done by running the above command again.

Alternatively, you can run booklit with the -s flag to start a HTTP server showing your generated content:

$ booklit -i hello.lit -o docs -s 8000

Then, browse to http://127.0.0.1:8000/hello.html. When you change anything, just refresh and your content will be rebuilt and served.

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!
}

Upon building this you should see something like:

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 will 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.

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 generally 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.