Xoa

Xoa is a basic generator of static websites. It takes care of rendering the content of web feeds and pages, while the user defines the directory and document structures.

Installation

Xoa is written in Fennel. The program depends on GNU roff and the following Lua libraries:

• Djot
• LuaFileSystem
• Scintillua lexers

Building is done with make(1p), findutils, and help2man. To install xoa under a certain prefix, run:

make install PREFIX=$prefix

Usage

$ xoa --help
Usage: xoa [-C directory] [-m modname] prefix
Generate a website from the working directory and put it under prefix.

Options:
  -C directory, --directory=directory
                     Change to directory before doing anything.
  -m modname, --module=modname
                     Load website configuration from modname (default: init).
  -h, --help         Print this message and exit.
  -v, --version      Print the version number of xoa and exit.

By default, xoa looks inside the current directory for a file named init.fnl or init.lua that returns a table with the following fields.

base-url

The base URL of the website must ends with a slash character, like "https://example.net/".

assets (optional)

Xoa expects assets to be an array of strings that are paths to files to be copied from the working directory to the prefix path, e.g. ["favicon.svg" "style.css" "path/to/an/image.png"].

pages

This is a mapping of the path to each page content in djot markup to a page attribute table with the following fields.

title

The page's title string.

summary (optional)

The page's summary string.

categories (optional)

An array of strings to be used in the Atom entry.

published (optional)

A value returned from os.time in UTC.

authors (optional)

See the top-level authors field below.

license (optional)

Atom entry's licensing information.

extra-markups (optional)

A table of extra djot markup strings, which if exists, get rendered into XHTML at extra-contents.

page-url-path

A function must be provided to determine the page URL path from the path to its content. It can be a simple substitution of the file extension like #($:gsub "%.djot$" ".html") or implement a complex path rewrite logic.

render-page

Xoa passes the page attribute table and its content rendered into XHTML to this function and expects a complete HTML document. It can be trivially implemented with string.format.

filter (optional)

If provided, this function should take two arguments, a page attribute table and a parsed djot document AST, and return a mapping between each tag and a function transforming an AST node of that tag.

Most people are probably interested in using such filter to turn djot symbols into arbitrary function calls. For example, the following filter would turn :rfc:{#4287} into a hyperlink to RFC 4287.

#{:symbol #(case $.alias
             :rfc {:t :link
                   :destination (.. "https://www.rfc-editor.org"
                                    "/rfc/rfc" $.attr.id ".html")
                   :c [{:t :str :s (.. "RFC " $.attr.id)}]})}

feeds (optional)

This is a mapping of each Atom feed output path to a table with the following fields.

title

The feed's title string.

select

A function being given a mapping between the path to each page's markup and the corresponding Atom entry to return an array of Atom entries, e.g.

#(icollect [path entry (pairs $)]
   (if (. pages path :published)
       entry))

authors

Each item in the website authors array is a table with the field name, and optionally, uri and email for the Atom feeds, for instance, [{:name "Alyssa P. Hacker" :email "alyssap@hacker.example"}].

icon-url-path (optional)

If provided, the icon URL path is used for the Atom feeds.

license (optional)

If provided, this licensing information is used in the Atom feeds.

Examples

The self-hosted documentation is defined in doc/init.fnl.

Contributing

Bug reports and patches should be sent to https://chim.loan/xoa/forum.

Copying

Xoa is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License version 3 or later.

See also

lua(1), fennel(1), djot documentation at https://chim.loan/xoa/uv/djot/.