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 (5020B)

      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 ## Introduction
      8 
      9 Satelito uses markdown (or HTML) for basic content and separate (but
     10 optional) lua files for metadata. There is no support for front
     11 matter, instead we rely on the power and versatility of the lua
     12 tables, in which we can write lua functions that will extend the
     13 functionality of our static site.
     14 
     15 For templates, Satelito uses the [etlua templating
     16 language](https://github.com/leafo/etlua). It is simple, but powerful,
     17 because it allows you to run lua script directly in templates.
     18 
     19 So, through the use of Satelito you become familiar with a lightweight
     20 programming language, who has fast execution, and short learning
     21 curve.
     22 
     23 ## Installation
     24 
     25 To install Satelito, you must have [Luarocks](https://luarocks.org/)
     26 and [Git](https://git-scm.com/) on your computer:
     27 <https://github.com/luarocks/luarocks/wiki/Download#installing>.
     28 
     29 Then in your terminal:
     30 
     31     luarocks install --server=https://luarocks.org/dev satelito --local
     32 
     33 If the installation went successfully you can test Satelito by invoking the help page:
     34 
     35     satelito -h
     36 
     37 ## Init a website
     38 
     39 To start a project you should use the `init` command:
     40 
     41 `$ satelito init`
     42 
     43 Then Satelito will `git clone` the
     44 [satelito-sample](https://soucy.cc/git/satelito-sample/files.html) in
     45 you `$HOME` directory.
     46 
     47 You should rename `~/satelito-sample` and edit `~/sample/config.lua`
     48 according to your needs.
     49 
     50 Then in the folder's project where is the `config.lua` file type:
     51 
     52     satelito make --export
     53 
     54 That's it, your new site is now built in the `public_html/` folder.
     55 
     56 ## Basic concepts and conventions
     57 
     58 ### The configuration file
     59 
     60 The `config.lua` file is the cornerstone by which Satelito goes to
     61 generate your website. You can edit it, add metadata and use them in
     62 your templates.
     63 
     64 The `paths` subtable tells Satelito where are content, templates and
     65 the public_html folders:
     66 
     67     paths = {
     68         content = 'content/',
     69         templates = 'templates/',
     70         public_html = 'public_html/',
     71     }
     72 
     73 And the `mimetypes` subtable determine what kind of assets will be
     74 export in your website tree:
     75 
     76     mimetypes = {
     77         'image/svg+xml',
     78         'image/gif',
     79         'image/jpeg',
     80         'image/png',
     81         'application/pdf',
     82     }
     83 
     84 
     85 ### Also a page generator
     86 
     87 Satelito is designed more like a **static page generator** than a
     88 *static site generator* (ssg), because with the command `pipe` it
     89 allows you to input markdown files (and HTML too) through the pipeline
     90 to create one page or a small group of pages, instead of rebuilding
     91 everything each time.
     92 
     93 Here's an example to build only one file with the output of the `echo`
     94 command:
     95 
     96     $ echo ~/satelito-sample/content/filmography/the-eclipse.md | satelito pipe
     97 
     98 Or all the files in the `filmography/` repository:
     99 
    100     $ find ~/satelito-sample/content/filmography/ | satelito pipe
    101 
    102 This choice brings versatility to Satelito. You can render only a part
    103 of your website without the needs to regenerate the whole project. And
    104 as the last two examples shows, this allows you to use it with other
    105 programs in the Unix toolbox!
    106 
    107 ### The rule of two
    108 
    109 Like I said above, with Satelito there is no possibility of *front
    110 matter* in markdown file. If you want metadata for your content, you
    111 have to create a lua file that will have the same name as the markdown
    112 file.
    113 
    114     -rw-r--r-- 1 hs hs 115 Fec 29 15:16 trip-to-the-moon.lua
    115     -rw-r--r-- 1 hs hs 801 Fec 29 15:17 trip-to-the-moon.md
    116 
    117 #### The metadata file anatomy
    118 
    119 A metadata file, in its simplest expression, should look like that:
    120 
    121     return {
    122       date = "2020-09-01",
    123       datetime = "14:49:00",
    124       title = "A Trip to the Moon",
    125     }
    126 
    127 `date`, `datetime` and `title`, are the only required fields.
    128 
    129 Note that Satelito will not return an error if a markdown file does
    130 not have a lua equivalent: an HTML file will be created with as title
    131 the basename of the file, then the current datetime.
    132 
    133 ## Usage
    134 
    135 The easiest way to build your website is with the `make` command. Go
    136 to the main folder, the one with your `config.lua`, and then:
    137 
    138   `satelito make --export`.
    139 
    140 The `--export` option is to write the files in the `public_html/`
    141 folder, otherwise it will only display all the HTML files in the
    142 terminal (it's the same behaviour for the `pipe` command).
    143 
    144 Search recursively for all the markdown (or HTML) files with `find`, and piped
    145 directly as input to `satelito` with the `pipe` command:
    146 
    147     `find ~/satelito-sample/content | satelito pipe`.
    148 
    149 Same thing but with `ag`:
    150 
    151     `ag '' --markdown --html -l ~/satelito-sample/content | satelito pipe`
    152 
    153 Search for all the markdown (or HTML) files of the first level with `find`:
    154 
    155     `find ~/satelito-sample/content -maxdepth 1 | satelito pipe`.
    156 
    157 Watch change with `entr` to rebuild the project:
    158 
    159     `find ~/satelito-sample/ | entr -s 'find ~/satelito-sample/content | satelito pipe --export && echo "~/satelito-sample rebuilded at $(date +%T)"'`