Prosody IM Static Site Generator

Introduction

This is a simple static site generator for https://prosody.im/. The pages were migrated from our old DokuWiki instance, including history, into Markdown files in a Mercurial repository.

Contributing

The site is managed with Mercurial, just like Prosody. See the page Contributing for general instructions.

Syntax

The site uses Pandocs Markdown. A short summary of the most commonly used syntax follows.

Basics

This is how you write bold or emphasised words, code and external links and internal links.

  • list
  • items
term
definition

Headers

Headers can have custom #anchors like so:

Headers without an explicit anchor gets one generated based on the header text itself (i.e. for use in the table-of-contents).

Page title and metadata

Each page should have a header block containing at least a title for the page, that also shows up as the first header on the page.

Alternatively, a YAML metadata block can be used to set more kinds of metadata and processing instructions.

Code blocks

Often docs need to show some example Lua code, which is done using code blocks like this:

Requirements

For building

Theme

Building

make
Builds the entire site

Special files

Apart from GNUmakefile which contains the rules and relationships between source files and finished HTML pages, there’s _template.html which is the HTML template that the source Markdown files are combined with into HTML pages.

The page _dirindex.md also has some special treatment, as it is meant for the Nginx Fancy Index module to produce directory listings. Because of how that module needs separate header and footer files, after _dirindex.html is built, sed is used to split it into _dirindex_header.html and _dirindex_footer.html.

Serving

Because there were no .html file extensions in Dokuwiki, all links are broken unless some rewrite tricks are used.

For nginx, it goes something like this:

location / {
    index index.html start.html;
    try_files $uri.html $uri $uri/ =404;

    location ~* (/.+)/$ {
        try_files $1.html $uri $uri.html $uri/ =404;
    }
}