diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 62 |
1 files changed, 62 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..7f53a8e --- /dev/null +++ b/README.md @@ -0,0 +1,62 @@ +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 `argent.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 containing the following: + +| Key | Type | Meaning | +|------------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------| +| site_directory | string | filename of the directory where the site files are located | +| layout_directory | string | filename of the directory where layouts are located | +| exclude | table | array of files and directories in the `site_directory` to exclude from the public site | +| include | table | array of files and directories in the `site_directory` to forcibly include (e.g. `.htaccess` files, since dotfiles are normally excluded) | +| keep | table | array of files and directories in the public result to not touch during site generation. | +| noprocess | table | array of files and directories in the `site_directory` to exclude from processing (e.g. lua files specified here will **not** be converted into HTML). | +| rss_include | table | array of files and directories to include in the site's `rss.xml` file. | + +### 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 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) |