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
95
96
97
98
|
* Directory layout
Here's the gist:
- ~/src/~ : website content
- ~/bin/~ : programs and such for generating the website from ~/src/~
- ~/out/~ : where the generated output goes
- ~/Makefile~ : invoke ~/bin/~ as appropriate
- ~/git-setup~ : set up git hooks (see below)
- ~/benchmark~ : runs ~make~ and reports how long each part took
The web server should serve the union of ~/src/~ and ~/out/~.
On the ~master~ branch, ~/out/~ is ignored. But ~git-setup~ will set
up a git post-commit hook to generate ~/out/~ and commit it to the
~pre-generated~ branch.
* Document metadata
Currently supported are Markdown (~.md~) and Org-mode (~.org~) files.
Each of these format supports embedding metadata in the document
(well, Markdown doesn't really, but the Pandoc syntax extension
~yaml_metadata_block~ adds it).
In Org-mode, this looks like
#+BEGIN_SRC
#+KEY: value
...rest of document...
#+END_SRC
In Markdown, this looks like
#+BEGIN_SRC
---
key: value
key2:
- any YAML values
---
...rest of document...
#+END_SRC
AFAIK, unfortunately Org-mode only has values as strings, no
structured data.
Pandoc may make use of some of these values internally when converting
to HTML. See the Org-mode and Pandoc documentation.
However, there are some of these that are used specially by the site
generator:
| attribute | default | standard | format |
|-----------------+---------------------------------+--------------------+--------------------------------------------|
| title | the first line of the file | Pandoc | string |
| author | "Andrew Murrell" | Pandoc | string or list |
| license | "CC BY-SA-3.0" | no | string |
| pandoc_flags | "" | no | string ("--foo --bar") |
| pandoc_format | either "markdown" or "org" | no | string ("markdown+extnsn1+extnsns2") |
| html_head_extra | "" | Org-mode | string |
| class | "" | no | string (CSS class to apply to ~<body>~) |
| tags | "" | LaTeX, kinda[fn:1] | string ("ES HB") or list (["ES", "HB"]) |
| published[fn:2] | most recent git commit for file | no | string (Ruby ~Date.parse()~) or date[fn:3] |
| updated[fn:2] | first git commit for file | no | string (Ruby ~Date.parse()~) or date[fn:3] |
[fn:1] The ~tags~ attribute is normally a list, but because I don't
know how to do a list in Org-mode, I made it take a
whitespace-separated string as well.
[fn:2] The "published"/"updated" terminology is borrowed from the Atom
specification (RFC 4287), and I intend them to have the same
semantics. The "standard" variable name is "date", but I thought that
was dreadfully ambiguous and confusing when the site generator deals
with two distinct dates.
[fn:3] At various times there have been bugs in the YAML parser
library that Pandoc uses, causing it to fail to parse dates, so I just
always put the date in quotes now, and let Ruby ~Date.parse()~ take
care of it.
* Make targets
- ~all~ (default) : generate all generated files
- ~serve~ : alias for ~serve-8000~
- ~serve-PORTNUMBER~ : Run an HTTP server on PORTNUMBER. Search
won't work.
* Make dependencies
- ~all~
- GNU Make
- Ruby
- Pandoc 1.17+
- scss
- ~serve-%~ (in addition to what is needed for ~all~)
- unionfs
- python3
|
