From af59bf74725937ab2be70fe5de711fa7e4ddfb02 Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Mon, 20 Jun 2011 06:55:12 -0400 Subject: Added docs and tests to attr_list ext. Closes #7. --- docs/extensions/attr_list.txt | 74 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 docs/extensions/attr_list.txt (limited to 'docs') diff --git a/docs/extensions/attr_list.txt b/docs/extensions/attr_list.txt new file mode 100644 index 0000000..6bfe07b --- /dev/null +++ b/docs/extensions/attr_list.txt @@ -0,0 +1,74 @@ +Attribute Lists +=============== + +Summary +------- + +An extension to Python-Markdown that adds a syntax to define attributes on +the various HTML elements in markdown's output. + +This extension is included in the standard Markdown library. + +Syntax +------ + +The basic syntax was inspired by [Maruku][]'s Attribute List feature. + +[Maruku]: http://maruku.rubyforge.org/proposal.html#attribute_lists + +### The List ### + +An example attribute list might look like this: + + {: #someid .someclass somekey='some values' } + +A word which starts with a hash `#` will set the id of an element. + +A word which starts with a dot `.` will add to the list of classes assigned to +an element. + +A key/value pair will assign that pair to the element. + +Be aware that while the dot syntax will add to a class, using key/value pairs +will always override the previously defined attribute. Consider the following: + + {: #id1 .class1 id=id2 class="class2 class3" .class4 } + +The above example would result in the following attributes being defined: + + id="id2 class="class2 class3 class4" + +### Block Level ### + +To define attributes for a block level element, the attribute list should +be defined on the last line of the block by itself. + + This is a paragraph. + {: #an_id .a_class } + +The above results in the following output: + +

This is a paragraph.

+ +The one exception is headers, as they are only ever allowed on one line. + + A setext style header {: #setext} + ================================= + + ### A hash style header ### {: #hash } + +The above results in the following output: + +

A setext style header

+

A hash style header

+ +### Inline ### + +To define attributes on inline elements, the attribute list should be defined +immediately after the inline element with no whitespace. + + [link](http://example.com){: class="foo bar" title="Some title! } + +The above results in the following output: + +

link

-- cgit v1.2.3