diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 93 |
1 files changed, 83 insertions, 10 deletions
@@ -1,21 +1,94 @@ # reploy -A redo of deployment of the R3 sites (cards for now). +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 haskell platform (e.g. with https://www.haskell.org/ghcup/) -- `cabal run site -- --help` shows options -- `cabal run site` builds a demo site -- `cabal install` produces and installs an executable `site` into the cabal - path (you can use it as a program directly) +- 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 +### Containerized use -Docker has insurmountable issues with producing the files with the right -permissions. Use `podman` instead: +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/r3/websites-dev/reploy +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) |