https://github.com/radekstepan/blad
A minimalist flat-file CMS with dynamic content
https://github.com/radekstepan/blad
cms
Last synced: 8 months ago
JSON representation
A minimalist flat-file CMS with dynamic content
- Host: GitHub
- URL: https://github.com/radekstepan/blad
- Owner: radekstepan
- License: agpl-3.0
- Created: 2012-06-30T23:48:46.000Z (almost 14 years ago)
- Default Branch: master
- Last Pushed: 2017-05-22T18:36:43.000Z (about 9 years ago)
- Last Synced: 2025-08-09T02:35:01.908Z (11 months ago)
- Topics: cms
- Language: JavaScript
- Homepage: http://www.micklemlab.org
- Size: 1.6 MB
- Stars: 11
- Watchers: 3
- Forks: 1
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# blað
A minimalist flat-file CMS with dynamic content.
[](https://travis-ci.org/radekstepan/blad)
[](https://david-dm.org/radekstepan/blad)
[](LICENSE)
## Features
1. Reads content from Markdown files and YAML front-matter.
1. No database or write access to disk needed.
1. In-memory cache maintains dynamic content defined in helper functions.
1. Powerful [Swig](http://paularmstrong.github.io/swig/) templating.
## Quickstart
```bash
$ 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.
```bash
$ ./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](http://paularmstrong.github.io/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:
```js
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.