Home

Getting Started

bwog is a static blog generator. Its features include:

You can see an example of the capabilities of wetd, the markup language bwog uses at Post 1: Examples.

Dependencies

bwog is dependent on Chez Scheme. The markup extensions this document website uses require tectonic, dvisvgm, and deno (for KaTeX and highlight.js) in addition to Chez Scheme.

Installation

Prepare a directory. This will be your repository hosting your files and assets, as well as the HTML output. Every subdirectory under it should have a config.ss file containing the configuration.

Configuration

Configuration fragments exist at the directory level and the file level. Configuration for bwog is mostly an ordinary Scheme program. The goal of such a program is often to modify *config* in an environment local to what it belongs to, and the resulting environment for a file/directory (and the *config* inside) is obtained by applying changes at every node on its path from the root, closer to the root first.

You should probably access local configuration with define-config-field, add-local-config and config because they are written to always refer to *config* through the value of (interaction-environment). If you define some function using *config* directly that is called in another environment, *config* in the environment in which the function is defined will be accessed because of lexical binding.

*config* is an alist with symbol keys, and when you modify it through add-local-config, the original *config* and the one you specify will be composed together. The specific behavior of this composition process can be customized using the macro define-config-field. The composition rule you pass to it is called every time a composition happens, with the values of the field the rule belongs to in the original and the new one passed to it. (#f is passed when it's absent) Builtin composition rules are use-parent, use-child, use-append, and use-string-append, which does what their names suggest.

The composition rules are stored in *composition-rules*. As with *config*, access it through interaction-environment. It's an alist with symbol keys, mapping from config field names to composition rules.

Refer to (maybe copy from) docs/config.ss if documentation is unclear. (it is)

Internally, (but because bwog runs your code, you need to know) directories are lists of the symbol dir, its environment, an alist with stems of the filenames as keys and file representations as values, and an alist with subdirectory names as keys and directory representations as values. Files are lists of the symbol file, its environment, its wetd tree and its HTML tree.

Required configuration

Four configuration fields are predefined: markup-processors, index-template, file-template, and after.

markup-processors is a list of pairs whose car is a predicate for whether this processor applies to a given wetd node, and cdr is the processor that takes a wetd node and returns an HTML node. They are attempted on the wetd node from front to back.

index-template and file-template are run by bwog to generate HTML trees for directory indexes and files respectively. index-template is given the root directory and a list of strings representing the path to the directory the index is in, and file-template is given the root directory, a list of strings representing the path to the file, and the file's internal representation.

after is run with the root directory, the path of the root directory on the filesystem, and a list of strings representing the path to the subdirectory. it will be run for every subdirectory.

wetd

wetd is the markup language for bwog. It is parsed in two phases: block level first, then inline level. Block level elements are parsed without knowledge of inline level elements. Elements are generic and require markup processors to convert them into HTML or any other target language.

In wetd files, the beginning is configuration for the file, terminated by a line that contains three hyphens (---).

Block elements

Containers start with a line that begins with one or more : characters. The number of : characters at the beginning of the start line and end line must match. A Scheme datum is read after the starting colons and (append datum (list children)) is the result, where children are inline elements read from the enclosed lines.

Raw blocks start with a line that begins with one or more ` characters. Again, the number of backtick characters at the beginning of the start and end lines must match. A Scheme datum is read after the starting backticks and (append datum (list string)) is the result, where string is the string enclosed by the block.

Leaf blocks take up one line only and start with one or more ! characters. A Scheme datum is read after the starting exclamation marks and inline elements are read from the remainder of the line. The result is (append datum (list children)).

Paragraphs are formed by consecutive ordinary lines.

Inline elements

Inline elements are marked with the @ character. If the @ character is followed by a `, * or another @, it's considered as an escaped character. Otherwise, the parser attempts to parse a datum from the port, then read the enclosed text. Enclosed text are raw if they are surrounded by the same number of backticks, or parsed according to inline element rules if they are surrounded by asterisks.

Templating

bwog comes with XML and XML-like language processors. They take document trees represented in S-expressions and prints them in a port. The format they accept is as follows: 

(tag alist)

for a void element, or 

(tag alist (list of children))

for non-void elements, where alist denotes the node attributes, with symbols for the key.

They also accept characters and strings. Raw strings can be denoted as follows: 

(raw raw-string)

Markup Processors

Markup Processors take wetd documents in the parsed form and return HTML trees as represented by S-expressions. They are pairs of a predicate for whether the current document tree should be processed by the processor, and a function taking local (file) config and the document tree, returning HTML tree.

Default Markup Processors

Default markup processors are defined in bwog.ss. Their usages can be found in the source code of Post 1: Examples.