Markdown Meta-Data Extension is an extension to the Python implementation of Markdown that adds a syntax for defining mete-data about a document. The Meta-Data extension is inspired by and follows the syntax of MultiMarkdown. Currently, this extension does not use the meta-data in any way, but simply provides it as a Meta attribute of a markdown instance for use by other extensions or directly by your python code.
Get the Code
You can view or download the latest from trunk.
Previous Versions
- (first public release)
Dependencies
License
The Markdown Meta-Data Extension is licensed under the BSD License.
Syntax
Meta-data consists of a series of keywords and values defined at the beginning if a markdown document like this:
Title: My Document
Summary: A brief description of my document.
Authors: Waylan Limberg
John Doe
Date: October 2, 2007
blank-value:
base_url: http://example.com
This is the first paragraph of the document.
The keywords are case-insensitive and may consist of letters, numbers, underscores and dashes and must end with a colon. The values consist of anything following the colon on the line and may even be blank. If a line is indented 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.
Accessing the Meta-Data
The meta-data is made available as a python dict in the Meta attribute of an instance of the Markdown class. For example, using the above document:
>>> md = markdown.Markdown(extensions = ['meta']) >>> html = md.convert(text) # new in markdown 1.6b; use str(md) in older versions >>> meta = md.Meta # get meta-data from instance >>> print meta { 'title' : ['My Document'], 'summary' : ['A brief description of my document.'], 'authors' : ['Waylan Limberg', 'John Doe'], 'date' : ['October 2, 2007'], 'blank-value' : [''], 'base_url' : ['http://example.com'] }
Note that the keys are all lowercase and the values consist of a list of strings where each item is one line for that key. This way, one could preserve 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 the developer.
Compatible Extensions
The following are extensions currently known to work with the Meta-Data Extension and the keywords they are known to support:
-
Markdown Abbreviations
-
abbr_files
-
-
Markdown WikiLinks
-
wiki_base_url -
wiki_end_url -
wiki_html_class
-
Misc
For more info you may want to read my blog posts related to markdown. The Python Markdown mailing list should be of assistance should you need help getting things to work. Bug reports and improvements are welcome (waylan [AT] gmail [DOT] com).
