Debian Codegraph @

docs/extensions/meta_data.md

raw
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`