1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
|
# 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)
|
