|
2 months ago | |
---|---|---|
bin | 3 months ago | |
satelito | 2 months ago | |
.editorconfig | 3 months ago | |
README.md | 2 months ago | |
satelito-dev-1.rockspec | 1 year ago | |
satelito-dev-2.rockspec | 8 months ago | |
satelito-dev-3.rockspec | 8 months ago | |
satelito-dev-4.rockspec | 2 months ago |
README.md
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)"'