README.md

blað

A minimalist flat-file CMS with dynamic content.

Features

1. Reads content from Markdown files and YAML front-matter.
2. No database or write access to disk needed.
3. In-memory cache maintains dynamic content defined in helper functions.
4. Powerful Swig templating.

Quickstart

$ npm install blad -g
$ blad --port 8080
# blad/4.0.0-alpha started on port 8080

Configuration

The following command will launch a blad server on port 5050, sourcing files from the example/ directory and keep all cached content for a period of 1 day.

$ ./bin/blad.js --port 5050 --source example/ --cache 1440

Content

The site pages are maintained as sets of Markdown files with YAML front-matter. The name corresponds to the url of the page so, for example, /content/people/radek.md will get mapped to the /people/radek URL.

Among the fields one can set in the front-matter, template is the most important one. It sets a Swig HTML file that will be used to render the page. Not specifying this property will make the page serve 204 No Content when accessed.

Fields are represented as key-value pairs of arbitrary depth.

Layouts

Is a place where Swig templates live. They can be extended and macros work too.

If a 404.html template is provided together with a document entitled 404.md, these will be rendered when a user tries to visit a page that does not exist.

You can access the URL of a page you are on by using the url key.

Relations

You can access content in other documents by using the relations helper object.

To get a list of top-level pages in the CMS use:

{% for page in rel.menu() %}
  {{ page.url }}
{% endfor %}

To get a list of sibling documents:

{% for page in rel.siblings(url) %}
  {{ page.url }}
{% endfor %}

You can get a list of children of depth n:

{% for page in rel.children(url, n) %}
  {{ page.url }}
{% endfor %}

Access the first existing parent document:

{% set parent = rel.parent(url) %}

Check if one document is the same as another or one of its descendants:

{% set isFamily = rel.isFamily('/people', '/people') %}

Or just check if one document is a child of another:

{% set isChild = rel.isChild('/people', '/people/radek') %}

Helpers

Are modules (in JS or CoffeeScript) that can be accessed at page render stage. Typically they will be used to access remote data to then be rendered in a page. In a YAML front-matter we would request a helper like so:

---
helpers:
  people: my_helper.js
---

The first time a page is rendered, the helper in my_helper.js is called. It is expected to be a function with two parameters, data and cb. The former is a map of key-value fields from the front-matter, the latter a callback for when the helper has done its job. As an example:

module.exports = (data, cb) => {
  // Do some work...

  // Call back.
  cb(null, result);
};

You can access 3rd party libraries here by defining them in package.json of the site.

The data is then accessible under the key people (in the example above) in the page layout and saved for --cache amount of time. This is a startup parameter and saves having us make potentially expensive operations every time a page is requested.

Public

All static content, like CSS and JS files, can be accessed here. Use /public/path in layouts when accessing these files.