commit cf78efdc1e4fb37d1d75a9eaa3f953799aa4cc02
parent 5d9bb5f92279e3b52681e248849e66d9bf6ab49a
Author: Hugo Soucy <hugo@soucy.cc>
Date: Thu, 22 Apr 2021 22:30:15 -0400
Update the README
Diffstat:
| M | README.md | | | 99 | ++++++++++++++++++++++++++++++++++++++++++++++++++----------------------------- |
1 file changed, 63 insertions(+), 36 deletions(-)
diff --git a/README.md b/README.md
@@ -4,11 +4,13 @@
Satelito is a static site generator (ssg) made with lua script.
-Satelito uses markdown 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.
+## 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](https://github.com/leafo/etlua). It is simple, but powerful,
@@ -26,11 +28,11 @@ and [Git](https://git-scm.com/) on your computer:
Then in your terminal:
- * `luarocks install --server=https://luarocks.org/dev satelito --local`.
+ 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`
+ satelito -h
## Init a website
@@ -45,43 +47,72 @@ you `$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
-### More like a page generator
+### The configuration file
-Satelito is designed more like a **static page generator** than a
-*static site generator* (ssg), because this app is only able to take
-one markdown at a time, otherwise it will throw an error:
+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 assets will be
+export in your website tree:
- $ satelito -f ~/satelito-sample/content/index.md satelito-sample/content/filmography/moonlight-serenade.md
+ mimetypes = {
+ 'image/svg+xml',
+ 'image/gif',
+ 'image/jpeg',
+ 'image/png',
+ 'application/pdf',
+ }
- Usage: satelito ([-f <file>] | [-p]) [-h] [-e] [<command>] ...
- Error: unknown command 'satelito-sample/content/filmography/moonlight-serenade.md'
+### Also a page generator
-The only way to build multiple markdown files, it's to input them
-through the pipeline. By example with the `find` program:
+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.
- $ find ~/satelito-sample/ -name '*.md' | satelito -p
+Here's an example to build only one file with the output of the `echo`
+command:
-Or with `ag` (the silver-searcher):
+ $ echo ~/satelito-sample/content/filmography/the-eclipse.md | satelito pipe
- $ ag '' --markdown -l ~/satelito-sample/ | satelito -p
+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 web site without the needs 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.
+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 a markdown file. If you want metadata for your content you
+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 hs0ucy hs0ucy 115 Fec 29 15:16 trip-to-the-moon.lua
- -rw-r--r-- 1 hs0ucy hs0ucy 801 Fec 29 15:17 trip-to-the-moon.md
+ -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
@@ -101,23 +132,19 @@ the basename of the file, then the current datetime.
## Usage
-Build a file with the `-f` option:
-
- `satelito -f ~/satelito-sample/content/index.md`.
-
-Search recursively for all the markdown files with `find`, and piped
-directly as input to `satelito` with the `-p` flag:
+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 -name '*.md' | satelito -p`.
+ `find ~/satelito-sample/content | satelito pipe`.
Same thing but with `ag`:
- `ag '' --markdown -l ~/satelito-sample/content | satelito -p`
+ `ag '' --markdown --html -l ~/satelito-sample/content | satelito pipe`
-Search for all the markdown files of the first level with `find`:
+Search for all the markdown (or HTML) files of the first level with `find`:
- `find ~/satelito-sample/content -maxdepth 1 -name '*.md' | satelito -p`.
+ `find ~/satelito-sample/content -maxdepth 1 | satelito pipe`.
Watch change with `entr` to rebuild the project:
- `find ~/satelito-sample/ | entr -s 'find ~/satelito-sample/content -name "*.md" | satelito -p -e && echo "~/satelito-sample rebuilded at $(date +%T)"'`
+ `find ~/satelito-sample/ | entr -s 'find ~/satelito-sample/content | satelito pipe --export && echo "~/satelito-sample rebuilded at $(date +%T)"'`
