Slab tutorial

In this tutorial, we'll explore:

• The basics of HTML and how Slab provides an alternative syntax
• Key features of Slab, including its concise element notation and templating capabilities
• How to use the slab command-line tool to build your projects
• Advanced concepts like as fragments and modularity

By the end of this tutorial, you'll have a solid foundation in Slab and be ready to start creating your own web content. Let's dive in and start exploring Slab!

HTML

Slab is a small markup language designed for authoring HTML. HTML itself is a markup language, so let's start with that.

HTML stands for HyperText Markup Language. Its purpose is to allow the writing of text enhanced with markup information. The markup provides additional structure and data to help computer software process the text. For example, the markup may indicate that one piece of text is a title and another piece is a paragraph, or it may indicate that some words need to be emphasized. The hypertext nature comes from the ability to mark words as links: when followed (e.g., by clicking with the mouse), they allow navigation to different pages referenced by attributes of the links.

Below, we show the same text twice, without and with HTML markup.

A short story

Alice quickly jumped over the lazy rabbit and disappeared under the tree.

<h1>A short story</h1>
<p>Alice <em>quickly</em> jumped over <a href="https://en.wikipedia.org/wiki/White_Rabbit">the lazy rabbit</a> and disappeared under the tree.</p>

In this example, we can see that the HTML markup is usually written by pairs of tags. For instance, the opening tag <h1> and corresponding closing tag </h1> are used to delimit "A short story" and specify that it is a level 1 heading. (The opening tag, closing tag, and text content together are called an element.) Within the opening tag <a> (short for "anchor", used to specify hyperlinks), we see the attribute "href", used to specify where the link goes to; in this case, a Wikipedia page.

The above HTML may look like this when interpreted by a web browser. Note how the word "quickly" is rendered in italics and how the words "the lazy rabbit" form a link.

Note: The exact fonts, text size, or link color used to render HTML are collectively called "styles". The styles to use are usually described by another language called CSS.

Slab, an alternative syntax

At its core, Slab is an alternative syntax for writing HTML. The above example written in Slab might look like this:

h1 A short story
p Alice <em>quickly</em> jumped over <a href="https://en.wikipedia.org/wiki/White_Rabbit">the lazy rabbit</a> and disappeared under the tree.

Note that Slab supports regular HTML: the h1 element uses the Slab syntax, but the em element is written as regular HTML. If we are not using raw HTML, the above example could also look like this:

h1 A short story
p Alice #{em quickly} jumped over #{a(href="https://en.wikipedia.org/wiki/White_Rabbit") the lazy rabbit} and disappeared under the tree.

The differences between Slab and HTML may not seem worthwhile if you write mostly text and little markup. Here is another example where the markup is a larger part of our content than the text.

ul
  li Item
  li Item
  li Item

<ul>
    <li>
        Item
    </li>
    <li>
        Item
    </li>
    <li>
        Item
    </li>
</ul>

In this case, the brevity of the Slab syntax to generate HTML elements is more apparent. This example also shows how the tree-structured nature of HTML is captured by indentation in Slab (note how the closing </ul> tag appears at the very bottom). In addition to a different but equivalent syntax to HTML, Slab offers something that doesn't exist in HTML: templating, which we'll look at in a next section.

Using the slab command-line tool

Slab is implemented as a command-line tool called slab. You can get a copy from its GitHub release page. At the time of writing, the only release available is version v0.0.3.0, which is offered for Linux (this is a statically-linked binary; it should work on any Linux distribution).

Here's a way to download it, rename it to slab, and mark it as an executable file:

$ curl -sL https://github.com/hypered/slab/releases/download/v0.0.3.0-alpha/slab-v0.0.3.0-linux-x86-64-musl -o /bin/slab
$ chmod +x /bin/slab

The slab binary supports a --help flag:

$ slab --help
slab 0.0.4.0 - A programmable markup language to generate HTML

Usage: slab COMMAND

  Slab is a programmable markup language to generate HTML.

Available options:
  -v,--version             Show version information
  -h,--help                Show this help text

Available commands:
  build                    Build a library of Slab templates to HTML
  watch                    Watch and build a library of Slab templates to HTML
  serve                    Watch and serve a library of Slab templates
  report                   Analyse a library of Slab templates
  render                   Render a Slab template to HTML
  run                      Execute a Slab template
  evaluate                 Evaluate a Slab template
  parse                    Parse a Slab template to AST
  generate                 Generate code corresponding to a Slab template
  classes                  Parse a Slab template and report its CSS classes
  fragments                Parse a Slab template and report its fragments

The two most useful commands are build and serve.

build requires an argument: the path to a directory containing files with a .slab extension. It translates these files, written in the Slab syntax, to HTML, and writes the result to a directory called _site. For example, this is how this website is generated:

$ slab build content/
Building ./_site/index.html...
Building ./_site/layout/page.html...
No generated content for content/layout/page.slab
Building ./_site/reference.html...
Building ./_site/tutorial.html...

In addition to the build command, the serve command is useful during development. It starts a local web server and automatically rebuilds your content as files change.

$ slab serve content/

With this command running, you can view your site at http://127.0.0.1:9000 in your web browser. Any changes you make to your .slab files will be reflected immediately without the need to manually refresh the page.

The serve command is especially useful if you make frequent changes and want to see the results quickly without having to manually rebuild your site each time.

Both commands support the --dist option. When building, it specifies the directory where the resulting HTML files must be written. When running the development server, it is used to specify a directory to serve additional resources, such as images or CSS files.

Templating

Slab is also a templating language: Slab documents are templates that can be combined with external data.

Let's assume we have a file named values.json with the following content:

[
  {
    "username": "Alice",
    "email": "alice@example.com"
  },
  {
    "username": "Bob",
    "email": "bob@example.com"
  }
]

JSON is another text-based syntax, this time used to represent data. In this example, the square brackets [ and ] are used to delimit a list of two objects. The objects themselves are delimited by the curly braces { and }, and each contains two fields named "username" and "email". The values corresponding to these fields are "Alice" and "alice@example.com", and "Bob" and "bob@example.com".

We can now write a Slab template that references the above JSON file and uses its content to fill the template:

let values = ../../data/values.json
ul
  for value in values
    li= value['username']

<ul>
    <li>
        Alice
    </li>
    <li>
        Bob
    </li>
</ul>

Referencing the JSON file is done by using the let ... = ... syntax to create a variable named "values". (We could choose a different variable name, such as "clients", instead of "values".) Now "values" is a list of objects, as described above. Then we use the for syntax to iterate through the list, and do two things: assign each object to the "value" variable in turn, and select the "username" field using the value['username'] syntax. We then format the username with a li element. Note that we use the li= syntax (and not li) when we want to produce the value of some code expression.

Next steps

After reading this short tutorial, you can read the reference page of this site to learn everything Slab has to offer.

If you find Slab useful in your projects, we'd love to hear from you! Please drop us a note with your feedback or share details about your project. We are excited to feature it in our upcoming list of projects using Slab.