yar

An incremental static site generator written in rust.

Powers my blog.

Status

This works, but it lacks polish. It's a work in progress.

Building

git clone https://github.com/AbooMinister25/yar
cd yar
cargo build --release

Usage

Quickstart

yar new my_site
cd my_site
yar serve

This will create a very basic scaffold for a site you can start building on top of.

Directory Structure

yar doesn't enforce any specific directory structure or file hierarchy, save from the following:

• Templates must be in templates/ (except for template pages, which will be discussed further down).
• The Config.toml, if present, must be in the directory that you run yar from.
• If you are using custom themes for syntect, you must specify the path to the directory they're stored in.

As long as these rules are followed, yar will spit out a static site from whatever directory organized in whatever way that you throw at it.

Incremental Builds

yar is incremental by default, meaning it'll only rebuild files that have been changed from the last run. This makes for fast iterative build times.

The first time the static site generator is run, yar will store every item processed, alongside the hash of its contents, in an sqlite database. The next time the static site generator is run, yar will compare the hashes of every item passed to it with its corresponding entry in the database, and will rebuild them if there are any changes. It will also build any new files that were not present in any previous runs.

This database is persisted in the site.db file—if you delete it, yar will rebuild all pages.

Sometimes, you may have a page that depends on certain global variables that are changed between builds. In this case, if these variables are modified, but your page is not modified, it will not be rebuilt. You can mitigate this using template pages, which allow you to define variables that a page depends on.

The idea is to eventually rework this and implement a more sophisticated dependency system, but until then, template pages are the suggested workaround.

You can force yar to run a clean build with the --clean flag, which will delete site.db and the output directory and run a clean build.

Template Pages

Template pages are a special kind of page that are both templates and pages at the same time—a template that ships with its own page.

They are a generalized way to create things like paginations, as well as pages that may depend on some global variable (and are thus rebuilt when this variable changes).

Here's a brief example of a pagination over a tags variable.

---
title = "All Tags"
dependencies = [
    "tags"
]

[pagination]
from = "tags"
every = 5
---

<h1> All Tags </h1>
{% for tag in pagination.items %}
<p> {{ tag }} </p>
{% endfor %}

Currently, template pages cannot be used to create paginations over collections of non-strings. This is a priority issue, and will be remedied soon.

Hooks

yar can run certain hooks upon the completion of a successful run of the static site generator. These hooks are arbitrary commands and can be used to do things like further postprocessing of content.

Here's a basic example.

# Config.toml
[hooks]
post = [
  { cmd = "echo 'hello world'" }
]

Settings

# Site specific configuration.
[site]
url = "..."  # The url of the site.
authors = [
    "..."
] # The authors of the site.
title = "..."  # The title of the site.
description = "..."  # The description of the site.
email = "..."  # An email to accompany the site with.
root = "..."  # The path to the root of the site, where `yar` will read in and process files from.
output_path = "..."  # The path `yar` will render the site to.
development = false  # Whether or not a development build is being run.
syntax_theme = "..."  # The syntax highlighting theme.
syntax_theme_path =  "..."  # The path to which syntax highlighting themes should be discovered at.

# Configuration for hooks.
[hooks]
post = [
    { cmd = "...", help = "..." }
]