argent
================================

*a super-simple static site generator*

Argent is a static site generator written in C and using Lua 5.1 for scripting. 
I wrote it because many other static site generators I experimented with were 
either very rigid and complex or had been written for old versions of their 
chosen language and no longer worked in the modern version. Argent brings its 
own Lua interpreter and is written in C99, and so it should run just about 
anywhere that you can compile POSIX programs.

installation
--------------------------------

```
git clone https://sanine.net/git/argent
mkdir argent/build
cd argent/build
cmake ..
make
```

Move the resulting `argent` binary to somewhere on your PATH (probably `~/bin`).


using argent
--------------------------------

You need to provide Argent with a configuration file. By default this file is 
`config.lua` in the current working directory; you can override that with the 
`-c [config_file]` command-line option. The configuration file should be a Lua 
script that returns a table. The keys for this table are listed below. None of 
these are mandatory, and if they are omitted their default values will be used.

| Key              | Type   | Default | Meaning                                                                                       |
|------------------|--------|---------|-----------------------------------------------------------------------------------------------|
| site_name        | string | (nil)   | the name of the site (used for RSS feeds, and may be used by layouts)                         |
| site_address     | string | (nil)   | the web address of the site root. required for RSS.                                           |
| site_description | string | (nil)   | a description of the site, used for RSS                                                       |
| site_copyright   | string | (nil)   | copyright message for RSS.                                                                    |
| site_directory   | string | site    | name of the directory where the site files are located                                        |
| output_directory | string | public  | name of the directory to store the output in                                                  |
| layout_directory | string | (nil)   | filename of the directory where layouts are located                                           |
| plugin_directory | string | (nil)   | directory to add to `package.path`                                                            |
| exclude          | table  | (nil)   | array of patterns. a file that matches any pattern will be excluded from the output.          |
| include          | table  | (nil)   | array of patterns. a file that matches will be included, even if it otherwise would not.      |
| keep             | table  | (nil)   | array of files and directories in the public result to not touch during site generation.      |
| noprocess        | table  | (nil)   | array of patterns. a file that matches will be output verbatim.                               |
| rss_include      | table  | (nil)   | array of patterns. if set, the site will create an RSS feed and include matching files in it. |

### site directory

This is the directory that will be compiled into the public site. All of the 
files within it are copied verbatim to the output directory, with the 
exception of `.lua` files, which should return tables with at least a markup 
key. They can also contain any other arbitrary keys, which will be passed on 
the layout function. Certain non-markup keys are always present, and have a 
default value which can be overridden by the page table.

| Key      | Type   | Meaning                                                                                                                                                     |
|----------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
| markdown | string | A markup key -- will be converted to HTML                                                                                                                   |
| html     | string | A markup key -- will be inserted into the resulting HTML file                                                                                               |
| layout   | string | Should match one of the layout files' filename (e.g. `layout1.lua` -> `layout='layout1'`) -- specifies a layout function for postprocessing. (default: nil) |
| title    | string | The content of the <title> tag. (default: the bare filename)                                                                                                |
| date     | string | A date for the page, which can be used by the layout function. (default: the file's actual modification date.)                                              |


### layouts

A layout is simply a `.lua` file that returns a function, taking as input 
`(string, table)`, where the string is the target page's HTML, and the table 
contains any non-markup keys from the target page's table. This table is 
guaranteed to contain a `title` and `date` key.

### rss

If the `rss_include` key in the configuration table is non-nil, then an 
`rss.xml` file will be generated in the output root, containing all of the 
pages specified by `rss_include` and sorted by date.


license
--------------------------------

This software is licensed under the [Anti-Capitalist Software License](https://anticapitalist.software)