diff options
Diffstat (limited to 'README.org')
| -rw-r--r-- | README.org | 80 |
1 files changed, 60 insertions, 20 deletions
@@ -54,20 +54,29 @@ Those dependencies are: * 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). +If you drop a file in the ~src/~ folder, the site generator will try +to turn it into usable HTML. The big caveat is that files *MUST* to +be in all lower case (this is to efficiently handle the requirement +that URLs be case-insensitive)! -In Org-mode, this looks like +Currently supported formats are: -#+BEGIN_SRC -#+KEY: value + - Markdown (~.md~) : converted with Pandoc + - Org-mode (~.org~) : converted with Pandoc + - PDF (~.pdf~) : embedded with PDF.js -...rest of document... -#+END_SRC +I don't need to tell you how to make these types of files. + +In addition to the raw content of the files, you'll want/need to set +metadata about the page. Each of these format supports embedding +metadata in the document. -In Markdown, this looks like +** Setting metadata: Markdown + +Metadata for Markdown files can be set by adding a block of YAML at +the beginning of the document, terminated with "---". This isn't +"standard" markdown, but is a common syntax extension (Pandoc calls it +~yaml_metadata_block~). #+BEGIN_SRC --- @@ -79,16 +88,47 @@ key2: ...rest of document... #+END_SRC +Pandoc may make use of some of these metadata attributes internally +when converting to HTML. See the Pandoc documentation. + +** Setting metadata: Org-mode + +Metadata for Org-mode files can be set by adding ~#+KEY: value~ lines +at the beginning of the document. + +#+BEGIN_SRC +#+KEY: value + +...rest of document... +#+END_SRC + +Pandoc may make use of some of these metadata attributes internally +when converting to HTML. See the Org-mode and Pandoc documentation. + 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. +** Setting metadata: PDF + +PDF files natively support embedding certain bits of metadata. The +bits that we use are: + + - title + - author + - creation date + - modification date + +If you need to set any other metadata attributes, or want to override +the values in the PDF (since setting them can be difficult), create +YAML file with the same name as the PDF file, but with the ~.yaml~ +file extension instead of ~.pdf~. + +** Metadata attributes that are handles specially -However, there are some of these that are used specially by the site +There are some metadata attributes that are used specially by the site generator: -| attribute | default | standard | format | +| attribute | default value | standard | format | |------------------+---------------------------------+----------+-------------------------------------------------| | title | the first line of the file | Pandoc | string | | author | ~config.yaml:default_author~ | Pandoc | string +or list+ [fn:1] | @@ -98,16 +138,16 @@ generator: | html_head_extra | "" | Org-mode | string | | class | "" | no | string (CSS class to apply to ~<body>~) | | 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] | +| published[fn:2] | first git commit for file | no | string (Ruby ~DateTime::parse()~) or date[fn:3] | +| updated[fn:2] | most recent 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 +same semantics. For "published"/"updated", the Pandoc "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 @@ -134,7 +174,7 @@ files: 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" +For example, adding "365 Tomorrows: A Simple Lament" to the "writing" directory: #+BEGIN_SRC @@ -155,7 +195,7 @@ attributes for local pages, but with fewer defaults: | 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] | +| published | value of ~updated~ [fn:4] | string (Ruby ~DateTime::parse()~) or date[fn:3] | | 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 |