* Directory layout Here's the gist: - ~/config.yaml~ : Top-level website configuration - ~/Makefile~ : duh - ~/git-setup~ : set up git hooks (see below) - ~/src/~ : website content - ~/out/~ : where the generated output goes - ~/bin/~ : programs you usually won't need to invoke directly - ~/lib/~ : the body of site generator (see also: ~/bin/sitegen~) - ~/doc/~ : additional documentation 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. More completely, ~git-setup~ sets up ~/bin/post-commit.githook~ as the git post-commit hook; which does two things: - run ~bin/auto-changelog~ (desribed in "ChangeLog", below) - run ~bin/pre-generate~ (described immediately above) * Make targets The Makefile provides several .PHONY targets of interest. - ~all~ (default) : Generate all generated files. While the main site is all generated by ~/bin/sitegen~ (which is called by the Makefile), other generated assets (CSS) is generated by the Makefile directly. - ~serve~ : Alias for ~serve-8000~ - ~serve-PORTNUMBER~ : Run an HTTP server on PORTNUMBER. Search won't work, and file names are case-sensitive. * Make dependencies As mentioned above, the generated static output is committed automatically to the ~pre-generated~ branch (assuming you've run ~git-setup~; so the server does't actually need all of the sitegen dependencies. However, the computer being used to commit does. Those dependencies are: - ~all~ - GNU Make - Ruby - Pandoc 1.17+ - scss - ~serve-%~ (in addition to what is needed for ~all~) - unionfs - python3 * Authoring pages 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 | ~config.yaml:default_author~ | Pandoc | string +or list+ [fn:1] | | license | ~config.yaml:default_license~ | 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 ~~) | | categories[fn:2] | "" | no | string ("ES HB") or list (["ES", "HB"]) | | published[fn:2] | most recent git commit for file | no | string (Ruby ~DateTime::parse()~) or date[fn:3] | | updated[fn:2] | first git commit for file | no | string (Ruby ~DateTime::parse()~) or date[fn:3] | [fn:1] We don't support lists of authors, though the Pandoc "standard" does. [fn:2] The "published"/"updated"/"categories" terminology is borrowed from the Atom specification (RFC 4287), and I intend them to have the same semantics. For "published"/"updated", there is a "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 ~DateTime::parse()~ take care of it. * Customizing index pages The generated index pages (directory listings) may be influenced by an ~index.yaml~ file placed in the ~/src/~ directory they describe. There are only 3 attributes that we look for in the ~index.yaml~ files: | attribute | default | format | |-----------+------------------------------+-------------------------| | title | File::basename(dirpath) | string | | author | ~config.yaml:default_author~ | string | | external | empty list | list of maps; see below | * Adding pages hosted elsewhere In the directory you wish for the externally hosted pages to appear in, add the metadata to the page to external list. For example, adding "356 Tomorrows: A Simple Lament" to the "writing" directory: #+BEGIN_SRC title: "Writing" external: - title: "365 Tomorrows: A Simple Lament" url: "http://365tomorrows.com/12/03/a-simple-lament/" published: "2013-12-03" categories: [FF] #+END_SRC The metadata attributes for the external pages are very similar to the attributes for local pages, but with fewer defaults: | attribute | default | format | |------------+------------------------------+--------------------------------------------------| | url | mandatory | string | | title | mandatory | string | | author | ~config.yaml:default_author~ | string | | categories | "" | string ("ES HB") or list (["ES", "HB"]) | | published | value of ~updated~ [fn:4] | string (Ruby ~DateTime::parse()~) or date[fn:b3] | | updated | value of ~published~ [fn:4] | string (Ruby ~DateTime::parse()~) or date[fn:3] | [fn:4] It is mandatory to set at least one of ~published~ or ~updated~. These externally hosted pages also show up in the Atom (RSS) feed. * The ChangeLog Whenever a you commit, post-commit hook runs ~bin/auto-changelog~, which will only continue to run if the commit touches a ~.org~ or ~.md~ file to the ~/src/~ directory (with the special case that it ignores files named ~index.md~ or ~changelog.md~). If the commit does add or change such a file, then it uses the git log to prepend an entry to ~/src/changelog.md~, and commits that. The format that it uses is loosely based on the GNU Coding Standards' recomendation for ~ChangeLog~ files. If you want to update the changelog manually, or edit an entry, feel free. But be warned that the first 3 lines of the file are reset every time ~auto-changelog~ runs.