| 1 |
title: Meta-Data Extension |
| 2 |
|
| 3 |
Meta-Data |
| 4 |
========= |
| 5 |
|
| 6 |
Summary |
| 7 |
------- |
| 8 |
|
| 9 |
The Meta-Data extension adds a syntax for defining meta-data about a document. |
| 10 |
It is inspired by and follows the syntax of [MultiMarkdown][]. Currently, |
| 11 |
this extension does not use the meta-data in any way, but simply provides it as |
| 12 |
a `Meta` attribute of a Markdown instance for use by other extensions or |
| 13 |
directly by your python code. |
| 14 |
|
| 15 |
This extension is included in the standard Markdown library. |
| 16 |
|
| 17 |
[MultiMarkdown]: https://fletcherpenney.net/multimarkdown/#metadata |
| 18 |
|
| 19 |
Syntax |
| 20 |
------ |
| 21 |
|
| 22 |
Meta-data consists of a series of keywords and values defined at the beginning |
| 23 |
of a markdown document like this: |
| 24 |
|
| 25 |
```md |
| 26 |
Title: My Document |
| 27 |
Summary: A brief description of my document. |
| 28 |
Authors: Waylan Limberg |
| 29 |
John Doe |
| 30 |
Date: October 2, 2007 |
| 31 |
blank-value: |
| 32 |
base_url: http://example.com |
| 33 |
|
| 34 |
This is the first paragraph of the document. |
| 35 |
``` |
| 36 |
|
| 37 |
The keywords are case-insensitive and may consist of letters, numbers, |
| 38 |
underscores and dashes and must end with a colon. The values consist of |
| 39 |
anything following the colon on the line and may even be blank. |
| 40 |
|
| 41 |
If a line is indented by 4 or more spaces, that line is assumed to be an |
| 42 |
additional line of the value for the previous keyword. A keyword may have as |
| 43 |
many lines as desired. |
| 44 |
|
| 45 |
The first blank line ends all meta-data for the document. Therefore, the first |
| 46 |
line of a document must not be blank. |
| 47 |
|
| 48 |
Alternatively, You may use YAML style delimiters to mark the start and/or end |
| 49 |
of your meta-data. When doing so, the first line of your document must be `---`. |
| 50 |
The meta-data ends at the first blank line or the first line containing an end |
| 51 |
deliminator (either `---` or `...`), whichever comes first. Even though YAML |
| 52 |
delimiters are supported, meta-data is not parsed as YAML. |
| 53 |
|
| 54 |
All meta-data is stripped from the document prior to any further processing |
| 55 |
by Markdown. |
| 56 |
|
| 57 |
Usage |
| 58 |
----- |
| 59 |
|
| 60 |
See [Extensions](index.md) for general extension usage. Use `meta` as the name |
| 61 |
of the extension. |
| 62 |
|
| 63 |
A trivial example: |
| 64 |
|
| 65 |
```python |
| 66 |
markdown.markdown(some_text, extensions=['meta']) |
| 67 |
``` |
| 68 |
|
| 69 |
Accessing the Meta-Data |
| 70 |
----------------------- |
| 71 |
|
| 72 |
The meta-data is made available as a python Dict in the `Meta` attribute of an |
| 73 |
instance of the Markdown class. For example, using the above document: |
| 74 |
|
| 75 |
```pycon |
| 76 |
>>> md = markdown.Markdown(extensions = ['meta']) |
| 77 |
>>> html = md.convert(text) |
| 78 |
>>> # Meta-data has been stripped from output |
| 79 |
>>> print html |
| 80 |
<p>This is the first paragraph of the document.</p> |
| 81 |
|
| 82 |
>>> # View meta-data |
| 83 |
>>> print md.Meta |
| 84 |
{ |
| 85 |
'title' : ['My Document'], |
| 86 |
'summary' : ['A brief description of my document.'], |
| 87 |
'authors' : ['Waylan Limberg', 'John Doe'], |
| 88 |
'date' : ['October 2, 2007'], |
| 89 |
'blank-value' : [''], |
| 90 |
'base_url' : ['http://example.com'] |
| 91 |
} |
| 92 |
``` |
| 93 |
|
| 94 |
Note that the keys are all lowercase and the values consist of a list of |
| 95 |
strings where each item is one line for that key. This way, one could preserve |
| 96 |
line breaks if desired. Or the items could be joined where appropriate. No |
| 97 |
assumptions are made regarding the data. It is simply passed as found to the |
| 98 |
`Meta` attribute. |
| 99 |
|
| 100 |
Perhaps the meta-data could be passed into a template system, or used by |
| 101 |
various Markdown extensions. The possibilities are left to the imagination of |
| 102 |
the developer. |
| 103 |
|
| 104 |
Compatible Extensions |
| 105 |
--------------------- |
| 106 |
|
| 107 |
The following extensions are currently known to work with the Meta-Data |
| 108 |
extension. The keywords they are known to support are also listed. |
| 109 |
|
| 110 |
* [WikiLinks](wikilinks.md) |
| 111 |
* `wiki_base_url` |
| 112 |
* `wiki_end_url` |
| 113 |
* `wiki_html_class` |