Slightly

Slightly is a small, client-side template engine that uses static markdown files
to manage content.

Usage

Include the following code within the head of your index page.

<script defer src="https://slightly.erayd.net/dist/slightly-latest.min.js" crossorigin></script>
<meta name="slightly-config" content="/config.json" />

If a template is not specified, then the index page will be used. All paths on
your site that do not map to a file should be configured on the webserver to
return the index page.

Configuration

Slightly uses two configuration methods. The first is a site-wide configuration
file, and the other is an optional YAML frontmatter section for each markdown
page.

Config File

The config file may be located wherever is convenient. The following meta tag
must be present:

<meta name="slightly-config" content="/url/for/config.json" />

The config file takes the following format:

{
    "template": "/url/for/template.html",
    "target": "#selector-to-inject-page-content",
    "prefix": "Title Prefix",
    "suffix": "Title Suffix"
}

Any value within this file may be overridden by individual pages. All are
optional.

YAML Frontmatter

Pages may include optional YAML frontmatter as follows:

---
title: "Page Title",
template: "/url/for/template.html",
target: "#selector-to-inject-page-content",
description: "This is the page meta description"
---
# Markdown Document
This is some markdown content.

The parameters available here override any that may be set in the config file.
All are optional.

Content

Content is provided as simple static markdown files, with optional YAML
frontmatter. It should be present on the webserver at the
request path, with a .md file extension.

Images

Images will be rendered inside <figure> blocks. If the image has an alt
attribute, the contents of that will be appended after the image as a
<figcaption>.

Some basic styling of the figure is possible using the fragment portion of the
image URL. This consists of a semicolon-separated set of key / value pairs. The
value is optional.

Any unrecognised key is added to the figure as a class, and the value is
discarded.

![Image caption](/url/of/image.jpg#right;w=50%;my-class)

The above example will display a right-floated figure, 50% wide, with the class
my-class.

404 Errors

In order to return the correct HTTP status code, any request for which the
request path does not have a corresponding markdown file (e.g. if /not-a-file
is requested, and the file /not-a-file.md does not exist) should be configured
to return a 404 status code. There are no other considerations necessary.

Custom 404 pages using the main template engine are not currently implemented,
but will be available in a future version.

Templates

Slightly templates are just regular HTML files. If you wish to include
sub-templates, you can do so as follows:

<div slightly-template="/path/to/sub-template.html" slightly-selector="#sub-fragment"></div>

The tag may be of any kind, and does not need to be a div. It will be replaced
by the included sub-template. The slightly-selector attribute is optional, but
if present then the first matching element of the sub-template will be used. If
absent, then the sub-template document element will be used.

Templates may be listed to any level, however care must be taken not to nest
them recursively.

Table of Contents

If you wish to include a table of contents, simply add the slightly-toc
attribute to any element. This element will be replaced with a generated TOC.
The TOC attribute may be used on more than one element, and may even appear
within a content markdown file.

The value of this attribute should be set to the maximum level of heading you
wish to include. By default, all headings will be included. If there are no
available headings that fit within the selected level, the TOC element will
simply be deleted.

<div slightly-toc="3"></div>

If the top level of the TOC contains only one heading, it will be omitted, and
the next level of heading will be promoted. This promotion mechanism does not
affect the level of heading selected by slightly-toc.