summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.org52
1 files changed, 38 insertions, 14 deletions
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] |