From 6d63ab23b09fd78b8c500cdc8b903cec551e125c Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Fri, 22 Dec 2017 13:07:11 -0500 Subject: README: fix typo --- README.org | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.org') diff --git a/README.org b/README.org index 6d27dc4..21e2891 100644 --- a/README.org +++ b/README.org @@ -134,7 +134,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 -- cgit v1.2.3 From 1e786e7807e41e7143588a84d085f019ed19b28a Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Fri, 22 Dec 2017 23:12:51 -0500 Subject: README: fix typo --- README.org | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.org') diff --git a/README.org b/README.org index 21e2891..1b9491e 100644 --- a/README.org +++ b/README.org @@ -155,7 +155,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 -- cgit v1.2.3 From 2214b9fa0cc8468b6a8c1e55b3642ede87862409 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Sat, 23 Dec 2017 13:25:55 -0500 Subject: README: fix obvious mixup between "published" and "updated" --- README.org | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'README.org') diff --git a/README.org b/README.org index 1b9491e..81ea619 100644 --- a/README.org +++ b/README.org @@ -98,8 +98,8 @@ generator: | 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] | +| 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. -- cgit v1.2.3 From d5cf54c2a5650e70577ebdd9b07ae2bdb91bf104 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Sat, 23 Dec 2017 13:26:35 -0500 Subject: README: reword sentence about not using Pandoc's "date" --- README.org | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'README.org') diff --git a/README.org b/README.org index 81ea619..8870768 100644 --- a/README.org +++ b/README.org @@ -106,8 +106,8 @@ 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 -- cgit v1.2.3 From 7c62b0a53c35f2cfce07469fb771ef0aa8f2302d Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Sat, 23 Dec 2017 21:31:25 -0500 Subject: README: revise the structure of the "Authoring pages" section. --- README.org | 52 ++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 38 insertions(+), 14 deletions(-) (limited to 'README.org') diff --git a/README.org b/README.org index 8870768..e8a3542 100644 --- a/README.org +++ b/README.org @@ -54,20 +54,28 @@ 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 -...rest of document... -#+END_SRC +I don't need to tell you how to make these types of files. -In Markdown, this looks like +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. + +** 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 +87,32 @@ 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. +** 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] | -- cgit v1.2.3 From efbd3731c986a8555869c184cda69ff9b910ce9f Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Sat, 23 Dec 2017 15:52:22 -0500 Subject: pdf support --- README.org | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'README.org') diff --git a/README.org b/README.org index e8a3542..e95aff5 100644 --- a/README.org +++ b/README.org @@ -63,6 +63,7 @@ Currently supported formats are: - Markdown (~.md~) : converted with Pandoc - Org-mode (~.org~) : converted with Pandoc + - PDF (~.pdf~) : embedded with PDF.js I don't need to tell you how to make these types of files. @@ -107,6 +108,21 @@ when converting to HTML. See the Org-mode and Pandoc documentation. AFAIK, unfortunately Org-mode only has values as strings, no structured data. +** 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 There are some metadata attributes that are used specially by the site -- cgit v1.2.3