95 lines
4 KiB
Markdown
95 lines
4 KiB
Markdown
|
|
# 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)
|