satelito

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

README.md (4117B)

      1 # Satelito
      2 
      3 [Beware! Satelito is under development, same for its documentation.]
      4 
      5 Satelito is a static site generator (ssg) made with lua script.
      6 
      7 Satelito uses markdown for basic content and separate (but optional)
      8 lua files for metadata. There is no support for front matter, instead
      9 we rely on the power and versatility of the lua tables, in which we
     10 can write lua functions that will extend the functionality of our
     11 static site.
     12 
     13 For templates, Satelito uses the [etlua templating
     14 language](https://github.com/leafo/etlua). It is simple, but powerful,
     15 because it allows you to run lua script directly in templates.
     16 
     17 So, through the use of Satelito you become familiar with a lightweight
     18 programming language, who has fast execution, and short learning
     19 curve.
     20 
     21 ## Installation
     22 
     23 To install Satelito, you must have [Luarocks](https://luarocks.org/)
     24 and [Git](https://git-scm.com/) on your computer:
     25 <https://github.com/luarocks/luarocks/wiki/Download#installing>.
     26 
     27 Then in your terminal:
     28 
     29   * `luarocks install --server=https://luarocks.org/dev satelito --local`.
     30 
     31 If the installation went successfully you can test Satelito by invoking the help page:
     32 
     33   * `satelito -h`
     34 
     35 ## Init a website
     36 
     37 To start a project you should use the `init` command:
     38 
     39 `$ satelito init`
     40 
     41 Then Satelito will `git clone` the
     42 [satelito-sample](https://soucy.cc/git/satelito-sample/files.html) in
     43 you `$HOME` directory.
     44 
     45 You should rename `~/satelito-sample` and edit `~/sample/config.lua`
     46 according to your needs.
     47 
     48 ## Basic concepts and conventions
     49 
     50 ### More like a page generator
     51 
     52 Satelito is designed more like a **static page generator** than a
     53 *static site generator* (ssg), because this app is only able to take
     54 one markdown at a time, otherwise it will throw an error:
     55 
     56     $ satelito -f ~/satelito-sample/content/index.md satelito-sample/content/filmography/moonlight-serenade.md
     57 
     58     Usage: satelito ([-f <file>] | [-p]) [-h] [-e] [<command>] ...
     59 
     60     Error: unknown command 'satelito-sample/content/filmography/moonlight-serenade.md'
     61 
     62 The only way to build multiple markdown files, it's to input them
     63 through the pipeline. By example with the `find` program:
     64 
     65     $ find ~/satelito-sample/ -name '*.md' | satelito -p
     66 
     67 Or with `ag` (the silver-searcher):
     68 
     69     $ ag '' --markdown -l ~/satelito-sample/ | satelito -p
     70 
     71 This choice brings versatility to Satelito. You can render only a part
     72 of your web site without the needs to regenerate the whole
     73 project. And as the last two examples show, this allows you to use it
     74 with other programs in the Unix toolbox.
     75 
     76 ### The rule of two
     77 
     78 Like I said above, with Satelito there is no possibility of *front
     79 matter* in a markdown file. If you want metadata for your content you
     80 have to create a lua file that will have the same name as the markdown
     81 file.
     82 
     83     -rw-r--r-- 1 hs0ucy hs0ucy 115 Fec 29 15:16 trip-to-the-moon.lua
     84     -rw-r--r-- 1 hs0ucy hs0ucy 801 Fec 29 15:17 trip-to-the-moon.md
     85 
     86 #### The metadata file anatomy
     87 
     88 A metadata file, in its simplest expression, should look like that:
     89 
     90     return {
     91       date = "2020-09-01",
     92       datetime = "14:49:00",
     93       title = "A Trip to the Moon",
     94     }
     95 
     96 `date`, `datetime` and `title`, are the only required fields.
     97 
     98 Note that Satelito will not return an error if a markdown file does
     99 not have a lua equivalent: an HTML file will be created with as title
    100 the basename of the file, then the current datetime.
    101 
    102 ## Usage
    103 
    104 Build a file with the `-f` option:
    105 
    106     `satelito -f ~/satelito-sample/content/index.md`.
    107 
    108 Search recursively for all the markdown files with `find`, and piped
    109 directly as input to `satelito` with the `-p` flag:
    110 
    111     `find ~/satelito-sample/content -name '*.md' | satelito -p`.
    112 
    113 Same thing but with `ag`:
    114 
    115     `ag '' --markdown -l ~/satelito-sample/content | satelito -p`
    116 
    117 Search for all the markdown files of the first level with `find`:
    118 
    119     `find ~/satelito-sample/content -maxdepth 1 -name '*.md' | satelito -p`.
    120 
    121 Watch change with `entr` to rebuild the project:
    122 
    123     `find ~/satelito-sample/ | entr -s 'find ~/satelito-sample/content -name "*.md" | satelito -p -e && echo "~/satelito-sample rebuilded at $(date +%T)"'`