# 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](https://en.wikipedia.org/wiki/Mustache_%28template_system%29).

## 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](https://lunrjs.com/).

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](http://mustache.github.io/mustache.5.html) 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)