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