diff options
-rw-r--r-- | HACKING.md | 14 | ||||
-rw-r--r-- | README.md | 5 | ||||
-rw-r--r-- | README.org | 97 | ||||
-rw-r--r-- | src/missing.txt | 12 |
4 files changed, 97 insertions, 31 deletions
diff --git a/HACKING.md b/HACKING.md deleted file mode 100644 index a21b577..0000000 --- a/HACKING.md +++ /dev/null @@ -1,14 +0,0 @@ -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 : see which files take longer to generate - -The web server should serve the union of /src/ and /out/. - -On `master`, /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. diff --git a/README.md b/README.md deleted file mode 100644 index d53fbc5..0000000 --- a/README.md +++ /dev/null @@ -1,5 +0,0 @@ -Dependencies: - - GNU Make - - Ruby - - Pandoc 1.17+ - - scss diff --git a/README.org b/README.org new file mode 100644 index 0000000..d373438 --- /dev/null +++ b/README.org @@ -0,0 +1,97 @@ +* 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 | +| 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 diff --git a/src/missing.txt b/src/missing.txt deleted file mode 100644 index 67de762..0000000 --- a/src/missing.txt +++ /dev/null @@ -1,12 +0,0 @@ -Writing/Programming "section"s - - addItem("Writing", - mkItem("http://365tomorrows.com/12/03/a-simple-lament/", - "365 Tomorrows: A Simple Lament", - [["FF", "Flash Fiction"]])); - - addItem("Programming", - mkItem("./DND/WaterdeepBazaar/WaterdeepBazaar.html", - "Waterdeep Bazaar: Marketplace Generator", - [["DM", "DMing Resource"], - ["WP", "WIP"]])); |