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)"'`