reploy

A complete REdo of dePLOYment of the R3 sites.

This is basically a small heap of haskell that produces a static HTML site out of a pile of markdown pages (with metadata in the YAML header blocks, similarly to what Jekyll does), complemented with a template and assets. The template language here is a slightly updated Mustache.

How to use this

• install the haskell platform (e.g. with https://www.haskell.org/ghcup/)
• cabal run reploy builds a really tiny demo site (run in project folder)
• cabal install produces and installs an executable reploy into the cabal path (usually ~/.cabal/bin) -- you can use it as a program directly

Optionally, there is a docker built directly from this repository.

Containerized use

Locally, Docker has insurmountable issues with producing the files with the right permissions. Use podman instead, roughly like this:

podman run -ti --rm -v $PWD:/data gitlab.lcsb.uni.lu:4567/lcsb/sps/reploy -d /data

Configuration and options

Run cabal run reploy -- --help (or just reploy --help if you installed the executable) to get a complete listing of available options with the documentation.

Generally, you will mostly need to set only -s (marks which directories to source), -d (marks where to put the generated HTML) and -u (sets the URL base in case your website won't sit in the domain root).

Search support

Reploy can generate a plaintext JSON dump of the site that is usable with Javascript search engines, such as lunr.

The way to produce the search indexes for lunr is described in the documentation at the top of scripts/make-search-index.js. By default, this works with the minimal search implementation present in the default template (present in assets/, templates/ and pages/search.md)

YAML options in page markdown

Required options

• mount (string): what should be the canonical URL of the page
• title (string): the name of the page for display in templates and page links

Optional

• template (string): name of the template file used to render the page. Defaulted from command options.
• search (boolean, default true): if not set, the page is omitted from the search index.
• toc (boolean or int, default 3): if false, no ToC is generated for the page. Otherwise the integer sets the depth of the ToC.
• timestamp (string): A description of the "timestamp" for the page, typically the date of the last page modification. For any file, this value is also defaulted from <filename>.timestamp (e.g., mypage.md.timestamp), which simplifies generation of the timestamps by external software (see scripts/source-timestamps.sh for an example of how to do that from git history)
• tags (array of strings): list of /-separated hierarchical tags ("categories") that are assigned to the page. The page will be listed in the category listings accordingly.
• redirect (array of strings): list of mounts that should redirect to this page (useful e.g. for old URLs, etc).

Template syntax

Reploy uses the "simple" vanilla Mustache enhanced by a single extra construction: {{?something}}xxx{{/something}} will render xxx only if something evaluates to "not falsey" (non-null, nonempty). This provides an easy but precise way to switch 2 branches of the code given the availability of some information in the base data, without any dependence on javascript implementation of negated truthiness -- the switch is perfectly complementary to {{^something}}xxx{{/something}} which only renders xxx if something js-evaluates to falsey (null, empty) value.

Other constructions:

• {{#something}}...{{/something}} can be used to "enter" the scope of something or unpack an array
• {{> template.html}} sources another template in the place
• {{{something}}} renders something WITHOUT escaping the HTML special characters (thus allowing injection of HTML code directly)