Key Principles and Features
This post was started on 2020-05-15. It was last modified on 2020-06-18. It was published on 2020-06-05.
Here are some thoughts on principles guiding the development of Colophon and the features they imply.
Reuse Existing Tools Where Possible
While Colophon is meant to be an experimental and new system, existing tools are
used whenever possible. This allows us to use high-quality, existing systems instead of
spending time and energy rolling our own (probably inferior) versions. For
example, the UNIX
make tool is used to check dependencies and generate
incremental builds, and the
tidy tool is used to clean
up generated HTML prior to publication.
Minimal Magic and Least Surprise
Using Colophon should be transparent and unsurprising. Colophon has very little “baked in” behavior. Configuration options are easy to access, understand and override. Instead of having configuration or fall back options backed into the source code, all configuration is read from a configuration file which may be overriden by users as needed. Instead of encoding metadata into filenames, Colophon encourages putting all metadata related to a page or post into the corresponding source file.
Simple Mapping from Input to Outputs
Other static site generators depend on having a particular directory structure for input, and can produce a very different output site structure. By contrast, Colophon keeps a much simpler mapping from input to output.
The output directory closely mirrors the input directory, and is separate from
it. Each file in the input should correspond to an output file in the same
location, just in the output directory. For example, to fix an error in
/blog/2020/02/hello-world.html, one can look only in
/blog/2020/02/hello-world.html.pm in the input directory, rather than
After generating the output directory using
colophon build, it should
possible to run
rsync, with no exclusions, from the output directory and
deploy the website. Both the input and output should be amenable to version
control for archiving and backup.