2 Basic Functions

Set the title of the current section, along with optional tags as repeated arguments.

For example, the title invocation for this section is:

\title{Basic Functions}{baselit}

To specify multiple tags, pass multiple arguments:

\title{I'm a taggy section!}{tag-1}{tag-1}

If no tags are specified, the section's tag defaults to a sanitized form of the title (e.g. I'm a fancy title! becomes im-a-fancy-title).

Denote auxiliary content which can be stripped in certain contexts without losing meaning.

Used within a title declaration to provide content that will show up on the section page itself but will be omitted when referencing the section. This is handy for sub-titles that you don't care to show anywhere but the section's page itself.

Example:

\title{Booklit\aux{: a pretty lit authoring system}}

This section, when referenced, would only show Booklit, but its header would include the content..

Introduce a sub-section, inheriting plugins of the outer section.

Each sub-section should conventionally begin with a call to \title to set its title.

For example, here's a full section containing a sub-section:

\title{I'm a parent section!}

Hello, world!

\section{
  \title{And I'm a child section!}

  Waaah! Waaaah!
}

Sections can be nested arbitrarily deep, however it is recommended to keep a maximum depth of two on a single page.

Sections can be rendered on separate pages by invoking \split-sections.

Load the Booklit document located at path (relative to the current section's file) and set it as a child section.

The included section does not inherit the plugins of the parent section. Instead, it should explicitly call \use-plugin on its own, so that it's self-contained.

Configure the renderer to generate a separate page for each immediate sub-section rather than inlining them under smaller headings.

When declared in a section, it overrules any \split-sections in the section and any child sections (recursively) in order to force them all on to one page. Each section's header sizing is preserved, however.

This is useful for having all of your content which is normally split across many pages joined in to an additional "single-page" format for quick skimming and searching.

Generate a block element that displays the table of contents from this section downward upon rendering. Often used in combination with \split-sections.

Configure the section to omit its children from table of contents listings. This is appropriate when the sub-sections within a section are not quite standalone; they may be brief and meant to be consumed all at once, so navigating to them individually would not make sense.

Register the plugin identified by name in the section. The plugin must be specified by --plugin on the command-line. See Plugins for more information.

Set the template's style to name. The renderer may then use this to present the section in a different way. See Styled Sections.

Define the partial name in the section with content as its content.

This is useful for communicating content to either Plugins or custom templates given to the HTML renderer.

Link to target (i.e. a URL), with display as the link's text.

For example, \link{Example}{https://example.com} becomes Example.

Note that the argument order is the reverse of \reference; writing tends to flow more naturally this way without a big URL interrupting the sentence.

Link to the target associated with tag. If the optional display argument is specified, it will be used as the link's content. Otherwise, the tag's configured display will be rendered.

For example, \reference{links-and-references} becomes Links & References.

Generate a target element that can be \referenced as tag. If display is specified, references will default to showing it as their link. Otherwise, tag itself will be the default.

As an example, we'll create a target element in the following paragraph, with the tag some-tag and display I'm just some tag!:

I'm a targetable paragraph.

Then, we'll reference it with \reference{some-tag}:

I'm just some tag!

Clicking the above link should take you to the paragraph.

Present text in a monospace font upon rendering.

If text is a single line, it is presented as inline code. If it is in paragraph form, it is presented as its own block. See Function Syntax for more information.

This is often used with {{two}} braces to preserve whitespace, or {{{three}}} to ignore escaping (in addition to preserving whitespace). See Function Syntax for more information.

For example:

I'm a sentence with some \code{code bits} in it.

...renders as:

I'm a sentence with some code bits in it.

While, this example:

\code{{
  This is a code block.
}}

...renders as:

This is a code block.

Present text in italics upon rendering.

Present text in bold upon rendering.

Present text ~20% larger upon rendering.

Present text ~20% smaller upon rendering.

Present text with a strike through it upon rendering.

Present text in ^superscript upon rendering.

Present text in _subscript upon rendering.

Renders the image at path inline.

Currently there is no "magic" that will do anything with the file specified by path - if it's a local path, you should make sure it's present in the directory that your documents are being generated into.

Render content indented a bit.

Render content in some way that conveys that it's a side-note.

Here I am!

Depending on your screen size, you should either see it to the right or above this line.

This is largely up to how you style them, though. You may want them to just look something like \inset if you don't have a "margin" in your design.

Render an unordered list of items.

• one
• two
• three!

Render an ordered list of items.

1. one
2. two
3. three!

Render a table with rows as its content.

The value for each row should be produced by using \table-row like so:

\table{
  \table-row{a}{b}{c}
}{
  \table-row{1}{2}{3}
}

The above example renders as:

Render a definition list with entries as its entries.

The value for each entry should be produced by using \definition like so:

\definitions{
  \definition{a}{1}
}{
  \definition{b}{2}
}

The above example renders as:

a

1

b

2