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

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