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 thetitle
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 afigure
element; this is what the conversion to HTML from Markdown does.
Directories
Pages
article/
- Generic pages which are not related to updates about me or the site.
links/
- Links of interest. These are basically public bookmarks.
publications/
- List of publications by yours truly.
update/
- Updates about me or the site.
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:
$ 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 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,
$ pandocCompilerWith mathReaderOptions mathWriterOptions compile
Table of contents
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.
See also
- Source for the web site on GitHub