diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/extensions/meta_data.txt | 32 |
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 |