commit 7dc46e300a3dce52aca31862525cfb17191727d2
parent 0ceb83743102ed70deca6699df3e3ea9024db08d
Author: Hugo Soucy <hugo@soucy.cc>
Date: Fri, 5 Feb 2021 16:39:18 -0500
Enhance the documentation in the README.
Diffstat:
| M | README.md | | | 68 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- |
1 file changed, 65 insertions(+), 3 deletions(-)
diff --git a/README.md b/README.md
@@ -32,11 +32,73 @@ If the installation went successfully you can test Satelito by invoking the help
* `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](https://soucy.cc/git/satelito-sample/files.html) in
+you `$HOME` directory.
+
+You should rename `~/satelito-sample` and edit `~/sample/config.lua`
+according to your needs.
+
+## Basic concepts and conventions
+
+### More like a page generator
+
+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:
+
+ $ satelito -f satelito-sample/content/index.md satelito-sample/content/filmography/moonlight-serenade.md
+
+ Usage: satelito ([-f <file>] | [-p]) [-h] [-e] [<command>] ...
+
+ Error: unknown command 'satelito-sample/content/filmography/moonlight-serenade.md'
+
+The only way to build multiple markdown files, it's to input them
+through the pipeline. By example with the `find` program:
+
+ $ find satelito-sample/ -name '*.md' | satelito -p
+
+Or with `ag` (the silver-searcher):
+
+ $ ag '' --markdown -l satelito-sample/ | satelito -p
+
+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.
+
+### Rule of Two
+
+With Satelito there is no possibility of *front matter* in a 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 Feb 4 15:16 trip-to-the-moon.lua
+ -rw-r--r-- 1 hs0ucy hs0ucy 801 Feb 4 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
- `find mySiteSrc/ -name '*.md' | satelito --export`
- `ag '' --markdown -l mySitesrc/ | satelito --export`
-
-<!-- Watch changes `find` et `entr`: -->
-<!-- - `find mySiteSrc/ | entr -s 'echo "Modification!" && find mySiteSrc/ -name "*.md" | satelito --export'` -->
