satelito

Static [web] site (or page) generator (ssg) made with Lua script.
git clone git://soucy.cc/satelito.git
Log | Files | Refs | README

commit cf78efdc1e4fb37d1d75a9eaa3f953799aa4cc02
parent 5d9bb5f92279e3b52681e248849e66d9bf6ab49a
Author: Hugo Soucy <hugo@soucy.cc>
Date:   Thu, 22 Apr 2021 22:30:15 -0400

Update the README

Diffstat:
MREADME.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)"'`