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.
Hakyll metadata included for individual resources.
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 metadata fields which can be defined for any page.
- 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.
- If defined, load KaTeX resources necessary for rendering math.
- If defined, load stylesheet responsible for bibliographic references.
- If defined, load stylesheet responsible for syntax highlighting.
Content for a robots
- A URL for an RSS feed.
If defined, the value for the
titlemetadata 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
titleHTML element. The top-level heading will only include the value for the
titlemetadata field regardless of whether this is defined or not.
The front page can define a
include-latest-update metadata field.
If defined, it will include the latest update on the front page.
These are particular CSS elements I may need to use manually.
CSS class used with SVG images, for those whose colors should never invert on dark mode.
The class should be associated with the
imgelement inside a
figureelement; this is what the conversion to HTML from Markdown does.
- Generic pages which are not related to updates about me or the site.
- Links of interest. These are basically public bookmarks.
- List of publications by yours truly.
- Updates about me or the site.
- Contains files related to generating stylesheets. They may be Haskell code for generating the stylesheets, or be CSS stylesheets themselves that are copied verbatim.
- Haskell code for generating diagrams.
- Generic files to be included as is on the site.
- Images to be included as is on the site.
- Files related to the server infrastructure. E.g., Apache configuration.
- Hakyll templates used by the site.
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.
$ haskellCompiler compile
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
cleanupIndexUrls is used to clean up such URLs in the generated files.
$ compile pandocCompiler>>= loadAndApplyTemplate "templates/default.html" defaultContext >>= cleanupIndexUrls
mathWriterOptions to make Pandoc render math.
$ pandocCompilerWith mathReaderOptions mathWriterOptionscompile
Table of contents
getTocOptionsWith to make Pandoc render a table of contents
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.
dropExtensions function strips all extensions from a route.
It is used for making URLs clean.
The modules under
Web.Site.Rules define the rules for each portion of the web site.
I have a convention of exporting
items functions from such modules.
rules function should be obvious.
It allows the central
Web.Site.Rules module to call the rules in its sub-modules.
items function returns the pattern which maps to resources
which should be included in the sitemap.
Web.Site.Rules.Sitemap module uses them to collect the URLs
to include in the sitemap for the web site.
- Source for the web site on GitHub