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:
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
