* 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 ~~) | | 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