aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorKernc <kerncece@gmail.com>2014-11-25 00:13:39 +0100
committerWaylan Limberg <waylan.limberg@icloud.com>2014-11-30 22:14:57 -0500
commitef6eb032b2e08f866b900cbc4d130b18200f712e (patch)
tree5a3582cb9b348be9b5842779df44b98b1006a6f7 /docs
parent1339e8b87f926745b781139df7a23798ce922197 (diff)
downloadmarkdown-ef6eb032b2e08f866b900cbc4d130b18200f712e.tar.gz
markdown-ef6eb032b2e08f866b900cbc4d130b18200f712e.tar.bz2
markdown-ef6eb032b2e08f866b900cbc4d130b18200f712e.zip
Add YAML support to Meta extension
By default, this only supports YAML deliminators (`---`) and adds no additional behavior. In other words, parsing is unchanged. However, with the `yaml` option set, PyYAML will parse the metadata. Thanks to @kernc for suggesting the idea and doing the work on this.
Diffstat (limited to 'docs')
-rw-r--r--docs/extensions/meta_data.txt32
1 files changed, 26 insertions, 6 deletions
diff --git a/docs/extensions/meta_data.txt b/docs/extensions/meta_data.txt
index 406755b..517d3e6 100644
--- a/docs/extensions/meta_data.txt
+++ b/docs/extensions/meta_data.txt
@@ -44,9 +44,16 @@ If a line is indented by 4 or more spaces, that line is assumed to be an
additional line of the value for the previous keyword. A keyword may have as
many lines as desired.
-The first blank line ends all meta-data for the document. Therefore, the first
-line of a document must not be blank. All meta-data is stripped from the
-document prior to any further processing by Markdown.
+The first blank line ends all meta-data for the document. Therefore, the first
+line of a document must not be blank.
+
+Alternatively, if the first line in the document is `---`, a YAML document
+separator, then the meta-data is searched for between it and the next `---`
+(or `...`) line. Even though YAML delimitors are supported, meta-data is
+not parsed as YAML unless the `yaml` option is set (see below).
+
+All meta-data is stripped from the document prior to any further processing
+by Markdown.
Usage
-----
@@ -54,7 +61,15 @@ Usage
See [Extensions](index.html) for general extension usage, specify `markdown.extensions.meta`
as the name of the extension.
-This extension does not accept any special configuration options.
+The following options are provided to configure the output:
+
+* **`yaml`**: Support meta-data specified in YAML format.
+
+ Default: `False`
+
+ If `yaml` is set to `True`, the lines between `---` separators are parsed
+ as a full YAML object. PyYAML is required for this, and a warning is
+ issued if PyYAML (or equivalent) isn't available.
Accessing the Meta-Data
-----------------------
@@ -85,8 +100,13 @@ line breaks if desired. Or the items could be joined where appropriate. No
assumptions are made regarding the data. It is simply passed as found to the
`Meta` attribute.
-Perhaps the meta-data could be passed into a template system, or used by
-various Markdown extensions. The possibilities are left to the imagination of
+Note, if `yaml` option is set, the resulting `Meta` attribute is the object as
+returned by `yaml.load()` and may deviate significantly from the above
+description (e.g. may be a list of dicts, with value objects other than
+strings, ...).
+
+Perhaps the meta-data could be passed into a template system, or used by
+various Markdown extensions. The possibilities are left to the imagination of
the developer.
Compatible Extensions