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.