Guide to writing for this web site

By Yoo Chung.

Published on 2023-03-18.

Updated on 2023-03-26.

Hakyll is a static site generator written in Haskell. The rules for generating a site are written in Haskell, and they can be customized with code.

The upshot is that Hakyll can be very flexible in the things it can be made to do, which I have done with this site. However, there are an increasing number of knobs that I have added for generating the site, so I need them written down somewhere. That somewhere is here.

Metadata

Hakyll metadata included for individual resources.

Standard

The fields title, description, published, and updated are standard Hakyll metadata fields with their usual meaning. They should be included in page metadata when possible.

I use the sane and sensibly lexicographically sorted date format. I.e., dates such as 2023-03-28.

Custom

Custom metadata fields which can be defined for any page.

extra-stylesheet

A URL for an extra stylesheet to load for the page. For loading stylesheets only loaded by a few pages; other stylesheets will usually have dedicated metadata fields.

include-math

If defined, load KaTeX resources necessary for rendering math.

include-bibliography-stylesheet

If defined, load stylesheet responsible for bibliographic references.

include-syntax-stylesheet

If defined, load stylesheet responsible for syntax highlighting.

robots

Content for a robots meta tag.

rss-feed-link

A URL for an RSS feed.

standalone-title

If defined, the value for the title metadata field will be the entirety of the title for the page. This is intended for the front page. Other pages are expected to have the site title included in the page title.

Note that this only applies to the text that goes inside the title HTML element. The top-level heading will only include the value for the title metadata field regardless of whether this is defined or not.

Front page

The front page can define a include-latest-update metadata field. If defined, it will include the latest update on the front page.

Style

These are particular CSS elements I may need to use manually.

keep-colors: CSS class used with SVG images, for those whose colors should never invert on dark mode. The class should be associated with the img element inside a figure element; this is what the conversion to HTML from Markdown does.

Directories

Support

css/: Contains files related to generating stylesheets. They may be Haskell code for generating the stylesheets, or be CSS stylesheets themselves that are copied verbatim.
diagrams/: Haskell code for generating diagrams.
files/: Generic files to be included as is on the site.
images/: Images to be included as is on the site.
server/: Files related to the server infrastructure. E.g., Apache configuration.
templates/: Hakyll templates used by the site.

Compiling

Generation from Haskell

haskellCompiler compiles items by running its input argument as Haskell code. The output will be taken from the standard output of the executed Haskell code.

For example:

compile $ haskellCompiler []

The code can be either Haskell or literate Haskell.

Cleaning up URLs

This site uses clean URLs. For most pages, nothing further needs to be done because they are routed to file names which serve as part of clean URLs in the first place.

However, some pages are routed to index.html files so that the directory can be the URL. This is not an issue for manually inserted URLs, but URLs automatically collected, such as the index of updates or the index of articles, will include the index.html string. cleanupIndexUrls is used to clean up such URLs in the generated files.

For example,

compile $
  pandocCompiler
    >>= loadAndApplyTemplate "templates/default.html" defaultContext
    >>= cleanupIndexUrls

Math support

Use mathReaderOptions and mathWriterOptions to make Pandoc render math.

For example,

compile $ pandocCompilerWith mathReaderOptions mathWriterOptions

Use getTocOptionsWith to make Pandoc render a table of contents if the toc metadata field is defined. It is passed another Pandoc writer option as an input argument so that it can be combined with other writer options.

Routes

The dropExtensions function strips all extensions from a route. It is used for making URLs clean.

Rules

The modules under Web.Site.Rules define the rules for each portion of the web site. I have a convention of exporting rules and items functions from such modules.

The rules function should be obvious. It allows the central Web.Site.Rules module to call the rules in its sub-modules.

The items function returns the pattern which maps to resources which should be included in the sitemap. The Web.Site.Rules.Sitemap module uses them to collect the URLs to include in the sitemap for the web site.