satelito

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

commit 15f633d8a42ccc8e6e98755b568f57a8ee529bdf
parent 471da19d4174da00f74e4fd54b2121134684d4cf
Author: Hugo Soucy <hugo@soucy.cc>
Date:   Mon,  3 Apr 2023 10:00:02 -0400

Merge branch 'dev/2023-04/verbose-mode-alpha' into dev/2022-12/purge-command

Diffstat:
MREADME.md | 106+++++++++++++++++++++++++++++++++++++------------------------------------------
MTODO.md | 2++
Msatelito/init.lua | 6+++++-
Msatelito/site.lua | 9+++++++++
4 files changed, 66 insertions(+), 57 deletions(-)

diff --git a/README.md b/README.md @@ -1,45 +1,40 @@ # Satelito -[Beware! Satelito is under development, same for its -[documentation](https://codeberg.org/hs0ucy/Satelito/wiki).] +**Warning! Satelito and its [documentation](https://codeberg.org/hs0ucy/Satelito/wiki) +are currently under development.** -Satelito is a static site generator (ssg) made with lua script. +Satelito is a static site generator (SSG) made with Lua. ## Introduction -Satelito uses markdown (or HTML) for basic content and separate (but -optional) lua files for metadata. There is no support for front -matter, instead we rely on the power and versatility of the lua -tables, in which we can write lua functions that will extend the -functionality of our static site. +Satelito uses Markdown (and HTML) for basic content and optionally Lua files for metadata. There is no front matter support; but Lua tables are used for storing functions that can extend the functionality of your site. -For templates, Satelito uses the [etlua templating -language](https://github.com/leafo/etlua). It is simple, but powerful, -because it allows you to run lua script directly in templates. +For templates, Satelito uses the [Etlua templating +language](https://github.com/leafo/etlua). It is simple but powerful, +because it allows you to run Lua scripts directly in templates. -So, through the use of Satelito you become familiar with [a -lightweight programming language](https://www.lua.org/about.html), who -has fast execution, and [short learning -curve](https://learnxinyminutes.com/docs/lua/). +Through the use of Satelito you become familiar with [Lua, a fast +lightweight programming language](https://www.lua.org/about.html) +that has a [small learning curve](https://learnxinyminutes.com/docs/lua/). ## Features -* Obviously ... Make a static website from markdown (or HTML) files. -* Satelito can also generate pages individually or by directory. -* Automatically create lists of subpages, for all index pages. +* Ability to create a static website from Markdown (or HTML) files. +* Can generate pages individually or by directory. +* Automatically creates lists of subpages, for all index pages. * Define [page collection](https://codeberg.org/hs0ucy/Satelito/wiki/Collection) - from directory name or page name. + from directory or page name. * Automatically creates Atom/RSS syndication files, for all index pages. -* Fast, a site with hundreds of pages can be generated in seconds. -* Hackable thanks to the lua script which can be used directly in +* Fast; a site with hundreds of pages can be generated in seconds. +* Hackable thanks to Lua which can be used directly in templates or configuration files. -* Automated creation of a sitemap.xml file. +* Can automatically create a sitemap.xml file. * Create [pagination](https://codeberg.org/hs0ucy/Satelito/wiki/Pagination) with sequential navigation. -* Etc. +* And more... ## Installation @@ -47,23 +42,23 @@ To install Satelito, you must have [Luarocks](https://luarocks.org/) and [Git](https://git-scm.com/) on your computer: <https://github.com/luarocks/luarocks/wiki/Download#installing>. -Then in your terminal: +Then in your terminal, run: luarocks install satelito --local -If the installation went successfully you can test Satelito by invoking the help page: +If the installation succeeded, you can test Satelito by invoking the help page: satelito -h ## Init a website -To start a project you should use the `init` command: +To create a new project, use the `init` sub-command: `$ satelito init` -Then Satelito will `git clone` the [satelito -sample](https://codeberg.org/hs0ucy/Satelito-sample) website in your -`$HOME` directory. +Then Satelito will clone the [satelito +sample](https://codeberg.org/hs0ucy/Satelito-sample) website into your +home directory. You should rename `~/satelito-sample` and edit `~/sample/config.lua` according to your needs. @@ -72,18 +67,18 @@ Then in the folder's project where is the `config.lua` file, type: satelito make --export -That's it, your new site is now built in the `public_html/` folder. +And that's it, your new site is now built in the `public_html/` folder. ## Basic concepts and conventions ### The configuration file -The `config.lua` file is the cornerstone by which Satelito goes to +The `config.lua` file is the file Satelito goes to generate your website. You can edit it, add metadata and use them in your templates. -The `paths` subtable tells Satelito where are content, templates and -the public_html folders: +The `paths` sub-table tells Satelito where the content, templates and +the public_html folders are: paths = { content = 'content/', @@ -91,8 +86,8 @@ the public_html folders: public_html = 'public_html/', } -And the `mimetypes` subtable determine what kind of *non-textual -content* will be export in your website tree: +The `mimetypes` sub-table determines what kind of *non-textual +content* will be exported in your website tree: mimetypes = { 'image/svg+xml', @@ -108,30 +103,30 @@ here](https://codeberg.org/hs0ucy/Satelito-sample/src/branch/master/config.lua). ### Also a page generator Satelito is designed more like a **static page generator** than a -*static site generator* (ssg), because with the command `pipe` it -allows you to input markdown files (and HTML too) through the pipeline +*static site generator* (SSG), because with the sub-command `pipe`, +you can input Markdown and HTML files through the pipeline to create one page or a small group of pages, instead of rebuilding everything each time. -Here's an example to build only one file with the output of the `echo` +Here's an example that builds only one file with the output of the `echo` command: $ echo ~/satelito-sample/content/filmography/the-eclipse.md | satelito pipe -Or all the files in the `filmography/` repository: +Or all of the files in the `filmography/` directory: $ find ~/satelito-sample/content/filmography/ | satelito pipe This choice brings versatility to Satelito. You can render only a part -of your website without the needs to regenerate the whole project. And -as the last two examples shows, this allows you to use it with other +of your website without needing to regenerate the whole project. And +as the last two examples show, this allows you to use it with other programs in the Unix toolbox! ### The rule of two Like I said above, with Satelito there is no possibility of *front -matter* in markdown file. If you want metadata for your content, you -have to create a lua file that will have the same name as the markdown +matter* in Markdown files. If you want metadata for your content, you +have to create a Lua file with the same name as the Markdown file. -rw-r--r-- 1 hs hs 115 Fec 29 15:16 trip-to-the-moon.lua @@ -139,7 +134,7 @@ file. #### The metadata file anatomy -A metadata file, in its simplest expression, should look like that: +A metadata file, in its simplest expression, should look like this: return { date = "2020-09-01", @@ -149,31 +144,31 @@ A metadata file, in its simplest expression, should look like that: `date`, `datetime` and `title`, are the only required fields. -Note that Satelito will not return an error if a markdown file does -not have a lua equivalent: an HTML file will be created with as title -the basename of the file, then the current datetime. +Note that Satelito will not return an error if a Markdown file does +not have a Lua equivalent: an HTML file will be created with the +name of the file, followed by the current date and time. ## Usage -The easiest way to build your website is with the `make` command. Go -to the main folder, the one with your `config.lua`, and then: +The easiest way to build your website is with the `make` sub-command. Go +to the main folder with your `config.lua` inside, and then run: satelito make --export. The `--export` option is to write the files in the `public_html/` folder, otherwise it will only display all the HTML files in the -terminal (it's the same behaviour for the `pipe` command). +terminal (the same behaviour applies for the `pipe` sub-command). -Search recursively for all the markdown (or HTML) files with `find`, and piped -directly as input to `satelito` with the `pipe` command: +Search recursively for all Markdown (or HTML) files with `find`, and pipe +directly as input to `satelito` with the `pipe` sub-command: - find ~/satelito-sample/content | satelito pipe. + find ~/satelito-sample/content | satelito pipe Same thing but with [`ag`](https://geoff.greer.fm/ag/): ag '' --markdown --html -l ~/satelito-sample/content | satelito pipe -Search for all the markdown (or HTML) files of the first level with `find`: +Search for all the Markdown and HTML files of the first level with `find`: find ~/satelito-sample/content -maxdepth 1 | satelito pipe. @@ -183,5 +178,4 @@ Watch change with [`entr`](http://eradman.com/entrproject/) to rebuild the proje ## Theme -There is no theme mechanism because it's not the goal to get in your -way with that. +There is no theme mechanism because it's not meant to get in your way with that. diff --git a/TODO.md b/TODO.md @@ -1,4 +1,6 @@ * Add a command to purge the `public_html/` folder. +* The `init` command should test if git is installed. * Make sure `list = false` and `feed = false` works. * Set a GPL 3 licence to Satelito. * Add an CLI option to change the base URL on build. +* Tags should be lowecase to bypass doublons. diff --git a/satelito/init.lua b/satelito/init.lua @@ -24,14 +24,18 @@ local args -- Set 'init' command init = parser:command('init', 'Init the sample website in your $HOME folder.') + -- Set 'pipe' command pipe = parser:command('pipe', 'Build the site by inputing one or more markdown files through the pipeline.') pipe:flag('-e --export', 'Export the outputed HTML in the *config.paths.public_html* folder.') + -- Set 'make' command make = parser:command('make', 'Build the site from his directory.') make:flag('-e --export', 'Export the outputed HTML in the *config.paths.public_html* folder.') +make:flag('-v --verbose', 'Displays in the terminal the source and destination of each content.') + -- Set the exec command -exec = parser:command('exec', 'Execute a script from the bin directory.') +exec = parser:command('exec', 'Execute a script from the site\'s bin directory.') exec:argument 'bin name' -- Set the reset command reset = parser:command('reset', 'Delete everything in the public_html directory.') diff --git a/satelito/site.lua b/satelito/site.lua @@ -36,6 +36,7 @@ function site.make(sitedata) local config = _G.Satelito.config local contentdir = _G.Satelito.contentdir local export = _G.Satelito.args['export'] + local verbose = _G.Satelito.args['verbose'] local make = _G.Satelito.args['make'] local publicdir = _G.Satelito.publicdir local templates = _G.Satelito.templates @@ -46,6 +47,10 @@ function site.make(sitedata) local feed_xml, feed_xml_path local paginated + if verbose then + io.write(' ¬ ./' .. config.paths.content..sitedata[i].relpath) + end + sitedata[i].index = i -- Lists @@ -135,6 +140,10 @@ function site.make(sitedata) if export then assets.export(sitedata[i]) end + + if verbose then + io.write(' > ./'.. config.paths.public_html:sub(1, -2) .. sitedata[i].rellink .. ' ✔ \n') + end end -- Make and export the sitemap.xml