|
4 months ago | |
---|---|---|
bin | 1 year ago | |
satelito | 4 months ago | |
.editorconfig | 1 year ago | |
.gitignore | 4 months ago | |
README.md | 4 months ago | |
TODO.md | 4 months ago | |
satelito-beta-1.rockspec | 5 months ago | |
satelito-beta-1.src.rock | 5 months ago | |
satelito-dev-1.rockspec | 2 years ago | |
satelito-dev-2.rockspec | 1 year ago | |
satelito-dev-3.rockspec | 1 year ago | |
satelito-dev-4.rockspec | 9 months ago | |
satelito-dev-5.rockspec | 6 months ago |
README.md
Satelito
Warning! Satelito and its documentation are currently under development.
Satelito is a static site generator (SSG) made with Lua.
Introduction
Satelito uses Markdown (and HTML) for basic content and optionally Lua files for metadata. There is no front matter support; but Lua tables are used for storing functions that can extend the functionality of your site.
For templates, Satelito uses the Etlua templating language. It is simple but powerful, because it allows you to run Lua scripts directly in templates.
Through the use of Satelito you become familiar with Lua, a fast lightweight programming language that has a small learning curve.
Features
- Ability to create a static website from Markdown (or HTML) files.
- Can generate pages individually or by directory.
- Automatically creates lists of subpages, for all index pages.
- Define page collection from directory 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 Lua which can be used directly in templates or configuration files.
- Can automatically create a sitemap.xml file.
- Create pagination with sequential navigation.
- And more...
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, run:
luarocks install satelito --local
If the installation succeeded, you can test Satelito by invoking the help page:
satelito -h
Init a website
To create a new project, use the init
sub-command:
$ satelito init
Then Satelito will clone the satelito sample website into 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
And 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 file Satelito goes to
generate your website. You can edit it, add metadata and use them in
your templates.
The paths
sub-table tells Satelito where the content, templates and
the public_html folders are:
paths = {
content = 'content/',
templates = 'templates/',
public_html = 'public_html/',
}
The mimetypes
sub-table determines what kind of non-textual
content will be exported 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 sub-command pipe
,
you can input Markdown and HTML files through the pipeline
to create one page or a small group of pages, instead of rebuilding
everything each time.
Here's an example that builds only one file with the output of the echo
command:
$ echo ~/satelito-sample/content/filmography/the-eclipse.md | satelito pipe
Or all of the files in the filmography/
directory:
$ find ~/satelito-sample/content/filmography/ | satelito pipe
This choice brings versatility to Satelito. You can render only a part of your website without needing to regenerate the whole project. And as the last two examples show, 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 files. If you want metadata for your content, you have to create a Lua file with 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 this:
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 the name of the file, followed by the current date and time.
Usage
The easiest way to build your website is with the make
sub-command. Go
to the main folder with your config.lua
inside, and then run:
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 (the same behaviour applies for the pipe
sub-command).
Search recursively for all Markdown (or HTML) files with find
, and pipe
directly as input to satelito
with the pipe
sub-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 and 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)"'
Theme
There is no theme mechanism because it's not meant to get in your way with that.