Satelito

[Beware! Satelito is under development, same for its documentation.]

Satelito is a static site generator (ssg) made with lua script.

Introduction

Satelito uses markdown (or HTML) for basic content and separate (but optional) lua files for metadata. There is no support for front matter, instead we rely on the power and versatility of the lua tables, in which we can write lua functions that will extend the functionality of our static site.

For templates, Satelito uses the etlua templating language. It is simple, but powerful, because it allows you to run lua script directly in templates.

So, through the use of Satelito you become familiar with a lightweight programming language, who has fast execution, and short learning curve.

Features

• Obviously ... Make a static website from markdown (or HTML) files.
• Satelito can also generate pages individually or by directory.
• Automatically create lists of subpages, for all index pages.
• Define page collection from directory name or page name.
• Automatically creates Atom/RSS syndication files, for all index pages.
• Fast, a site with hundreds of pages can be generated in seconds.
• Hackable thanks to the lua script which can be used directly in templates or configuration files.
• Automated creation of a sitemap.xml file.
• Create pagination with sequential navigation.
• Etc.

Installation

To install Satelito, you must have Luarocks and Git on your computer: https://github.com/luarocks/luarocks/wiki/Download#installing.

Then in your terminal:

luarocks install --server=https://luarocks.org/dev satelito --local

If the installation went successfully you can test Satelito by invoking the help page:

satelito -h

Init a website

To start a project you should use the init command:

$ satelito init

Then Satelito will git clone the satelito sample website in your $HOME directory.

You should rename ~/satelito-sample and edit ~/sample/config.lua according to your needs.

Then in the folder's project where is the config.lua file, type:

satelito make --export

That's it, your new site is now built in the public_html/ folder.

Basic concepts and conventions

The configuration file

The config.lua file is the cornerstone by which Satelito goes to generate your website. You can edit it, add metadata and use them in your templates.

The paths subtable tells Satelito where are content, templates and the public_html folders:

paths = {
    content = 'content/',
    templates = 'templates/',
    public_html = 'public_html/',
}

And the mimetypes subtable determine what kind of non-textual content will be export in your website tree:

mimetypes = {
    'image/svg+xml',
    'image/gif',
    'image/jpeg',
    'image/png',
    'application/pdf',
}

See an example of a configuration file here.

Also a page generator

Satelito is designed more like a static page generator than a static site generator (ssg), because with the command pipe it allows you to input markdown files (and HTML too) through the pipeline to create one page or a small group of pages, instead of rebuilding everything each time.

Here's an example to build only one file with the output of the echo command:

$ echo ~/satelito-sample/content/filmography/the-eclipse.md | satelito pipe

Or all the files in the filmography/ repository:

$ find ~/satelito-sample/content/filmography/ | satelito pipe

This choice brings versatility to Satelito. You can render only a part of your website without the needs to regenerate the whole project. And as the last two examples shows, this allows you to use it with other programs in the Unix toolbox!

The rule of two

Like I said above, with Satelito there is no possibility of front matter in markdown file. If you want metadata for your content, you have to create a lua file that will have the same name as the markdown file.

-rw-r--r-- 1 hs hs 115 Fec 29 15:16 trip-to-the-moon.lua
-rw-r--r-- 1 hs hs 801 Fec 29 15:17 trip-to-the-moon.md

The metadata file anatomy

A metadata file, in its simplest expression, should look like that:

return {
  date = "2020-09-01",
  datetime = "14:49:00",
  title = "A Trip to the Moon",
}

date, datetime and title, are the only required fields.

Note that Satelito will not return an error if a markdown file does not have a lua equivalent: an HTML file will be created with as title the basename of the file, then the current datetime.

Usage

The easiest way to build your website is with the make command. Go to the main folder, the one with your config.lua, and then:

satelito make --export.

The --export option is to write the files in the public_html/ folder, otherwise it will only display all the HTML files in the terminal (it's the same behaviour for the pipe command).

Search recursively for all the markdown (or HTML) files with find, and piped directly as input to satelito with the pipe command:

find ~/satelito-sample/content | satelito pipe.

Same thing but with ag:

ag '' --markdown --html -l ~/satelito-sample/content | satelito pipe

Search for all the markdown (or HTML) files of the first level with find:

find ~/satelito-sample/content -maxdepth 1 | satelito pipe.

Watch change with entr to rebuild the project:

find ~/satelito-sample/ | entr -s 'satelito make --export && echo "Rebuilt at $(date +%T)"'