1Meta-Data 2========= 3 4Summary 5------- 6 7An extension to Python-Markdown that adds a syntax for defining meta-data about 8a 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 10way, but simply provides it as a `Meta` attribute of a markdown instance for 11use by other extensions or directly by your python code. 12 13[MultiMarkdown]: http://fletcherpenney.net/MultiMarkdown_Syntax_Guide#metadata 14 15This extension has been a part of the Markdown library since 2.0. 16 17Syntax 18------ 19 20Meta-data consists of a series of keywords and values defined at the beginning 21of 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 33The keywords are case-insensitive and may consist of letters, numbers, 34underscores and dashes and must end with a colon. The values consist of 35anything following the colon on the line and may even be blank. If a line is 36indented 4 or more spaces, that line is assumed to be an additional line of the 37value for the previous keyword. A keyword may have as many lines as desired. 38The first blank line ends all meta-data for the document. Therefore, the first 39line of a document must not be blank. All meta-data is stripped from the 40document prior to any further processing by markdown. 41 42Accessing the Meta-Data 43----------------------- 44 45The meta-data is made available as a python Dict in the `Meta` attribute of an 46instance 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 65Note that the keys are all lowercase and the values consist of a list of 66strings where each item is one line for that key. This way, one could preserve 67line breaks if desired. Or the items could be joined where appropriate. No 68assumptions are made regarding the data. It is simply passed as found to the 69`Meta` attribute. 70 71Perhaps the meta-data could be passed into a template system, or used by 72various markdown extensions. The possibilities are left to the imagination of 73the developer. 74 75Compatible Extensions 76--------------------- 77 78The following are extensions currently known to work with the Meta-Data 79Extension 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