Debian Codegraph @

docs/extensions/attr_list.md

raw
1 title: Attribute Lists Extension
2
3 # Attribute Lists
4
5 ## Summary
6
7 The Attribute Lists extension adds a syntax to define attributes on the various
8 HTML elements in markdown's output.
9
10 This extension is included in the standard Markdown library.
11
12 ## Syntax
13
14 The basic syntax was inspired by Maruku's Attribute Lists feature (see [web archive][Maruku]).
15
16 [Maruku]: https://web.archive.org/web/20170324172643/http://maruku.rubyforge.org/proposal.html
17
18 ### The List
19
20 An example attribute list might look like this:
21
22 ```text
23 {: #someid .someclass somekey='some value' }
24 ```
25
26 A word which starts with a hash (`#`) will set the id of an element.
27
28 A word which starts with a dot (`.`) will be added to the list of classes
29 assigned to an element.
30
31 A key/value pair (`somekey='some value'`) will assign that pair to the element.
32
33 Be aware that while the dot syntax will add to a class, using key/value pairs
34 will always override the previously defined attribute. Consider the following:
35
36 ```text
37 {: #id1 .class1 id=id2 class="class2 class3" .class4 }
38 ```
39
40 The above example would result in the following attributes being defined:
41
42 ```text
43 id="id2" class="class2 class3 class4"
44 ```
45
46 HTML includes support for some attributes to be a single term, like `checked`, for example. Therefore, the attribute
47 list `{: checked }` would result in `checked` if the [output format](../reference.md#output_format) is `html` or
48 `checked="checked"` if the output format is `xhtml`.
49
50 Curly braces can be backslash escaped to avoid being identified as an attribute list.
51
52 ```text
53 \{ not an attribute list }
54 ```
55
56 Opening and closing curly braces which are empty or only contain whitespace are ignored whether they are escaped or
57 not. Additionally, any attribute lists which are not located in the specific locations documented below are ignored.
58
59 The colon after the opening brace is optional, but is supported to maintain consistency with other implementations.
60 Therefore, the following is also a valid attribute list:
61
62 ```text
63 { #someid .someclass somekey='some value' }
64 ```
65
66 In addition, the spaces after the opening brace and before the closing brace are optional. They are recommended as
67 they improve readability, but they are not required.
68
69 The Attribute List extension does not have any knowledge of which keys and/or values are valid in HTML. Therefore, it
70 is up to the document author to ensure that valid keys and values are used. However, the extension will escape any
71 characters in the key which are not valid by replacing them with an underscore. Multiple consecutive invalid
72 characters are reduced to a single underscore.
73
74 ### Block Level
75
76 To define attributes for a block level element, the attribute list should
77 be defined on the last line of the block by itself.
78
79 ```text
80 This is a paragraph.
81 {: #an_id .a_class }
82 ```
83
84 The above results in the following output:
85
86 ```html
87 <p id="an_id" class="a_class">This is a paragraph.</p>
88 ```
89
90 An exception is headers, as they are only ever allowed on one line.
91
92 ```text
93 A setext style header {: #setext}
94 =================================
95
96 ### A hash style header ### {: #hash }
97 ```
98
99 The above results in the following output:
100
101 ```html
102 <h1 id="setext">A setext style header</h1>
103 <h3 id="hash">A hash style header</h3>
104 ```
105
106 !!! seealso "See Also"
107 By default, the [Fenced Code Blocks](./fenced_code_blocks.md#attributes) extension includes limited support for
108 attribute lists. To get [full support](./fenced_code_blocks.md#keyvalue-pairs), both extensions must be enabled.
109
110 ### Inline
111
112 To define attributes on inline elements, the attribute list should be defined
113 immediately after the inline element with no white space.
114
115 ```text
116 [link](http://example.com){: class="foo bar" title="Some title!" }
117 ```
118
119 The above results in the following output:
120
121 ```html
122 <p><a href="http://example.com" class="foo bar" title="Some title!">link</a></p>
123 ```
124
125 If the [tables](./tables.md) extension is enabled, attribute lists can be defined on table cells. To differentiate
126 attributes for an inline element from attributes for the containing cell, the attribute list must be separated from
127 the content by at least one space and be defined at the end of the cell content. As table cells can only ever be on
128 a single line, the attribute list must remain on the same line as the content of the cell.
129
130 ```text
131 | set on td | set on em |
132 |--------------|-------------|
133 | *a* { .foo } | *b*{ .foo } |
134 ```
135
136 The above example results in the following output:
137
138 ```html
139 <table>
140 <thead>
141 <tr>
142 <th>set on td</th>
143 <th>set on em</th>
144 </tr>
145 </thead>
146 <tbody>
147 <tr>
148 <td class="foo"><em>a</em></td>
149 <td><em class="foo">b</em></td>
150 </tr>
151 </tbody>
152 </table>
153 ```
154
155 Note that in the first column, the attribute list is preceded by a space; therefore, it is assigned to the table cell
156 (`<td>` element). However, in the second column, the attribute list is not preceded by a space; therefore, it is
157 assigned to the inline element (`<em>`) which immediately preceded it.
158
159 Attribute lists may also be defined on table header cells (`<th>` elements) in the same manner.
160
161 ### Limitations
162
163 There are a few types of elements which attribute lists do not work with. As a reminder, Markdown is a subset of HTML
164 and anything which cannot be expressed in Markdown can always be expressed with raw HTML directly.
165
166 __Code Blocks:__
167
168 : Code blocks are unique in that they must be able to display Markdown syntax. Therefore, there is no way to
169 determine if an attribute list is intended to be part of the code block or intended to define attributes on the
170 wrapping element. For that reason, the extension ignores code blocks. To define attributes on code blocks, the
171 [codehilite] and [fenced code blocks] extensions provide some options.
172
173 [codehilite]: code_hilite.md
174 [fenced code blocks]: fenced_code_blocks.md
175
176 __Nested Elements:__
177
178 : Markdown provides mechanisms for nesting various block level elements within other elements. However, attribute
179 lists only ever get applied to the immediate parent. There is no way to specify that an attribute list should be
180 applied some number of levels up the document tree. For example, when including an attribute list within a
181 blockquote, the attribute list is only ever applied to the paragraph the list is defined in. There is no way to
182 define attributes on the `blockquote` element itself.
183
184 __Implied Elements:__
185
186 : There are various HTML elements which are not represented in Markdown text, but only implied. For example, the
187 `ul` and `ol` elements do not exist in Markdown. They are only implied by the presence of list items (`li`). There
188 is no way to use an attribute list to define attributes on implied elements, including but not limited to the
189 following: `ul`, `ol`, `dl`, `table`, `thead`, `tbody`, and `tr`.
190
191 ## Usage
192
193 See [Extensions](index.md) for general extension usage. Use `attr_list` as the
194 name of the extension.
195
196 This extension does not accept any special configuration options.
197
198 A trivial example:
199
200 ```python
201 markdown.markdown(some_text, extensions=['attr_list'])
202 ```