commit 97adb6e43849e18cb2c7e550090cc663cee78925
parent 4c383923a227ac2954e9f1e8d0c03197d3a66313
Author: Jeremy <jtbx@duck.com>
Date: Thu, 1 Dec 2022 00:09:02 +0000
Fix spelling and grammar mistakes in README.md
Diffstat:
| M | README.md | | | 106 | +++++++++++++++++++++++++++++++++++++------------------------------------------ |
1 file changed, 50 insertions(+), 56 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.
