Rough

Rough is a very simple and very opinionated tool for generating small gallery/ showcase/portfolio websites. Once you've built it or obtained a pre-built executable, just do rough <source dir> <build dir> to generate your site. For example, rough src out.

Source format

A site generated with this tool consists of:

• A single HTML index file.
• Any number of project files, each their own HTML file.
• Any number of static files, such as images, CSS, and JavaScript.

Below, src/ will be used for the source directory, and out/ will be used for the output directory. However, these are configurable as mentioned above.

Project files

Project files will be read from src/projects. Each project file should be a Markdown file with YAML front matter. They will be rendered to out/projects, with whatever extension they have replaced with .html.

A file called src/project.html must also be present. This is a Tera template, which will be used to render each project file. The following context variables are available:

• meta: The YAML front matter.
• content: The Markdown content, rendered as HTML.

The index file

A file called src/index.html must be present. It is another Tera template, this time used just once to render the index file. Just one context variable is available: projects. This is a list, each element of which is the YAML front matter for one of the project files.

The index file is rendered to out/index.html.

Static files

Any files in src/static/ will be recursively copied to out/static/.

Markdown flavour

Markdown parsing and rendering is done by pulldown-cmark, which should be CommonMark compliant. The following non-commonmark extensions are added:

• GitHub Flavoured Markdown (GFM) tables
• GFM Task Lists
• GFM Strikethrough
• pulldown-cmark's footnotes
• pulldown-cmark's smart punctuation
• pulldown-cmark's heading attributes
• A custom extension which removes wrapping paragraph tags when they surround a sole image.

YAML frontmatter should be at the start of the document, delineated by three dashes on their own line, both above and below the frontmatter. For example:

---
title: Hello World!
slug: hello_world
description: My first ever file.
---

Hia!!