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