Rotuli static site compiler

A work in progress to become the most universal content processor.

.. image:: rotuliinuse.jpg :alt: people using rotuli :width: 99%

Figure 1: numerous rotuli have been used since the Roman Empire.

(Some fools claim that the term is "generator_" instead of compiler, but original content is generated by people, not software.)

.. _generator: https://www.staticgen.com/

Philosophy

A very pure and generic library, and a simple command line tool to pull and extrude content.

• Rotuli goal number one is to stay dumb and format-agnostic; it just is a support structure for your data, making it slightly easier to present what you have. What you have and how you have it is your business.
• Rotuli is also the plural form of rotulus_, an ancient roll that holds written information.
• Text content in, markup (if any) gets rendered, goes through its template with metadata, final rendered document is squeezed out. Repeat for each special content file. Non-special stuff is just copied.
• Identical directory listings for input and output. No "posts" directories, i.e., "routing" is trivial.
• Markup, metadata and template languages shall be anything you want (rst, yaml and jinja/tera for now).
• Additional features are built on metadata and template structure.

.. _rotulus: https://en.wikipedia.org/wiki/Rotulus

Rotuli is generic; it assumes nothing about your site. The content does not even need to be a website. Use it for a book if you like. Render PDFs if you prefer that format (when the template system supports that). Rotuli only provides rendering logic, metadata handling, page grouping and some template filters. The content does not know that it's being massaged.

Rotuli does not even have config files. Config files are evil because global variables are evil. Treat your pieces of data as individuals.

No template code is allowed in the source data, because data should be tool-agnostic. Handy shortcuts for images or code listings or page links or something? Sorry, no. Use a modern markup language and persistent urls.

Core features

• Consistent input and output file hierarchy
• Fast incremental builds for iterative, realtime work and minimized waste
• Markup processing for structuring the content
• Document metadata for describing the content
• Template engine for presenting the content
• Content groups by shared metadata keys
• Draft metadata key for excluding content unless specified

The content group feature is simple, significant and powerful.

Implicit features

For example:

• Trivial links to source repository for each rendered page
• Multilingual content: use the metadata and groups to link translations together
• Categories aka tags aka keywords: group content together in the metadata and use templates to list them
• Automatic by-date groups to list content (e.g., blog posts or news) based on year, month or day
• Listings of page kinds such as blog entries, tutorials and project entries via the content groups
• Links to next and previous pages in a collection based on the current page index in a group

Why

• Something simple, something generic, yet something very specific
• Someone wanted to have a hobby project for learning the Rust_ programming language
• The name is quite fun if you think about it (and apparently more unique than Rotulus_ these days unlike in 2016 when this project was started and abandoned for four years)
• The name starts with the same letter as the programming language

.. _Rust: https://www.rust-lang.org/ .. _more unique than Rotulus: https://github.com/search?q=rotulus

Why not

The very generic and content agnostic business means that some compromises have to be done. For example:

• Some redundancy in metadata (e.g., multilingual groups need unique keys, and urls are convenient unique keys)
• Blog url hierarchy can be /year/month/day/title/ but the date still needs to be specified in the metadata
• Explicit lack of blog-specific features may turn you away, but rotuli will have extension support some day
• There's no "serve debug mode" to present the rendered data - if you don't have a local httpd, look elsewhere

TODO

• Library/cli tool separation
• Documentation
• Production things such as image hardlinks to avoid big repetitive copies
• Image thumbnails
• Syntax-hilighted code listings
• Other markup/metadata/template engines
• A bunch of internal things
• Perf benchmarking
• Some kinds of extensions for specific features without forking the whole codebase