Setting up Configuration

After taking a week off for the holidays, I decided to try my hand at updating wanderer again with more features.

Besides HTML generation and image processing, there are two more features that I think are necessary for me to use this as my general-purpose site generator:

  1. A way to create a list of posts, automatically pulling titles and dates (and excerpts?) from a post’s content.
  2. A way to remove a page from the build, or change the URL in the final site (e.g. for ‘private links’)

I’ll think about #1 later - this time, I decided to tackle #2.

I’ve been using toml as the language for writing configuration for wanderer, mostly because I dislike yaml (I could probably support JSON too and get rid of the toml dependency, but alas I’ve gotten used to toml.)

There are three layers of configuration:

Site-wide configuration is passed into the builder function, and is typically found in config.toml in the base directory where wanderer is run.

Directory-level configuration is written in a _.toml file in a content directory. This file isn’t copied over to the build directory, but rather added to the configuration for that directory only. It recursively applies to sub-directories.

Every built (so .md for now) content file can also add configuration by starting the file with ---, adding toml-frontmatter, and ending the frontmatter with ---

The content is passed into template, so any top-level values in the config can be used as variables in the frame.

Any single page’s configuration object is a combination of the project, directory, and file-level configurations, and the configuration is processed both at the directory and at the file level.

At the directory level:

  • If private is set to true, the entire directory is skipped when building the site.
  • If dir is set, the build step will create that directory at the path of dir (relative to the build path), instead of copying over the content’s directory name.

At the file level:

  • if private is set to true, that file is skipped when building the site.
  • if rename is set, the build step will use that as the filename rather than copying over the file’s original name.

This should handle all of the cases where I’d need to rename or omit files. Unfortunately, this system is a bit of a mess, and isn’t well-tested, so I might edit things around as I continue iterating. I’m also not sure yet where documentation would live, but it should be linked here once it exists (if I remember to put it here, that is).

UPDATE January 12 2020: I’ve also added the possibility of using +++ as frontmatter separators since that’s apparently typical for TOML, and allows for TOML frontmatter syntax highlighting in Markdown files.