From 83382bcefb246f1169b0d01375fcd86cd05b031e Mon Sep 17 00:00:00 2001 From: Tiago Serafim Date: Sun, 2 Sep 2012 20:12:53 -0300 Subject: Initial version with insufficient tests and no docs. --- markdown/extensions/admonition.py | 136 ++++++++++++++++++++++++++++++++++++++ tests/extensions/admonition.html | 19 ++++++ tests/extensions/admonition.txt | 17 +++++ tests/extensions/test.cfg | 3 + tests/test_extensions.py | 56 +++++++++++++--- 5 files changed, 221 insertions(+), 10 deletions(-) create mode 100644 markdown/extensions/admonition.py create mode 100644 tests/extensions/admonition.html create mode 100644 tests/extensions/admonition.txt diff --git a/markdown/extensions/admonition.py b/markdown/extensions/admonition.py new file mode 100644 index 0000000..d8a95d3 --- /dev/null +++ b/markdown/extensions/admonition.py @@ -0,0 +1,136 @@ +#!/usr/bin/env python + +""" +Admonition extension for Python-Markdown +======================================== + +Adds rST-style admonitions. Inspired by [rST][] feature with the same name. + +The syntax is (followed by an indented block with the contents): + !!! [optional title] + +Where `type` is one of the followings: + attention, caution, danger, error, hint, important, note, tip, warning + +The above types have the appropriated title by default (i.e: note => Note) + +It's also possible to create custom types (with default CSS classes and Titles) +see the docs for more info. + +A simple example: + !!! note + This is the first line inside the box. + +Outputs: +
+

Note

+

This is the first line inside the box

+
+ +You can also specify the title and CSS class of the admonition: + !!! custom "Did you know?" + Another line here. + +Outputs: +
+

Did you know?

+

Another line here.

+
+ +[rST]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#specific-admonitions + +By [Tiago Serafim](http://www.tiagoserafim.com/). + +""" + +import re +import markdown +from markdown.util import etree + +DEFAULT_STYLES = { + # 'id': ('CSS_class', 'Display Name') + 'attention': ('attention', 'Attention'), + 'caution': ('caution', 'Caution'), + 'danger': ('danger', 'Danger'), + 'error': ('error', 'Error'), + 'hint': ('hint', 'Hint'), + 'important': ('important', 'Important'), + 'note': ('note', 'Note'), + 'tip': ('tip', 'Tip'), + 'warning': ('warning', 'Warning'), +} + + +class AdmonitionExtension(markdown.Extension): + """ Admonition extension for Python-Markdown. """ + + def __init__(self, configs): + self.config = { + 'styles': DEFAULT_STYLES.copy(), + } + + def extendMarkdown(self, md, md_globals): + """ Add Admonition to Markdown instance. """ + md.registerExtension(self) + + md.parser.blockprocessors.add('admonition', + AdmonitionProcessor(md.parser, self.config), + '_begin') + + +class AdmonitionProcessor(markdown.blockprocessors.BlockProcessor): + + CLASSNAME = 'admonition' + CLASSNAME_TITLE = 'admonition-title' + RE = re.compile(r'(?:^|\n)!!!\ ?([\w\-]+)(?:\ "?([^"\n]+)"?)?') + + def __init__(self, parser, config): + markdown.blockprocessors.BlockProcessor.__init__(self, parser) + self.config = config + + def test(self, parent, block): + sibling = self.lastChild(parent) + return self.RE.search(block) or \ + (block.startswith(' ' * self.tab_length) and sibling and \ + sibling.get('class', '').find(self.CLASSNAME) != -1) + + def run(self, parent, blocks): + sibling = self.lastChild(parent) + block = blocks.pop(0) + m = self.RE.search(block) + + if m: + block = block[m.end() + 1:] # removes the first line + + block, theRest = self.detab(block) + + if m: + klass, title = self.get_class_and_title(m.group(1), m.group(2)) + div = etree.SubElement(parent, 'div') + div.set('class', u'%s %s' % (self.CLASSNAME, klass)) + if title: + p = etree.SubElement(div, 'p') + p.text = title + p.set('class', self.CLASSNAME_TITLE) + else: + div = sibling + + self.parser.parseChunk(div, block) + + if theRest: + # This block contained unindented line(s) after the first indented + # line. Insert these lines as the first block of the master blocks + # list for future processing. + blocks.insert(0, theRest) + + def get_class_and_title(self, klass, title): + styles = self.config['styles'] + style = styles.get(klass, None) + if style: + return style[0], title or style[1] + else: + return klass, title + + +def makeExtension(configs={}): + return AdmonitionExtension(configs=configs) diff --git a/tests/extensions/admonition.html b/tests/extensions/admonition.html new file mode 100644 index 0000000..f28bcfd --- /dev/null +++ b/tests/extensions/admonition.html @@ -0,0 +1,19 @@ +

Some text

+
+

Note

+

A normal paragraph here

+
    +
  1. first
    2. +
  2. second
    3. +
+
+

More text and stuff.

+
+

Did you know?

+

You can customize the title of the admonition

+
+
+

And now...

+

For something completely different.

+

You can also use a custom CSS class name.

+
\ No newline at end of file diff --git a/tests/extensions/admonition.txt b/tests/extensions/admonition.txt new file mode 100644 index 0000000..e8db239 --- /dev/null +++ b/tests/extensions/admonition.txt @@ -0,0 +1,17 @@ +Some text + +!!! note + A normal paragraph here + + 1. first + 2. second + +More text and stuff. + +!!! note "Did you know?" + You can customize the title of the admonition + +!!! mycustomcssclass "And now..." + For something completely different. + + You can also use a custom CSS class name. diff --git a/tests/extensions/test.cfg b/tests/extensions/test.cfg index ac8a747..e83aa62 100644 --- a/tests/extensions/test.cfg +++ b/tests/extensions/test.cfg @@ -29,3 +29,6 @@ extensions=fenced_code [sane_lists] extensions=sane_lists + +[admonition] +extensions=admonition diff --git a/tests/test_extensions.py b/tests/test_extensions.py index 15feb6b..ca1520e 100644 --- a/tests/test_extensions.py +++ b/tests/test_extensions.py @@ -2,7 +2,7 @@ Python-Markdown Extension Regression Tests ========================================== -A collection of regression tests to confirm that the included extensions +A collection of regression tests to confirm that the included extensions continue to work as advertised. This used to be accomplished by doctests. """ @@ -59,7 +59,7 @@ class TestFencedCode(unittest.TestCase): def testBasicFence(self): """ Test Fenced Code Blocks. """ - text = ''' + text = ''' A paragraph before a fenced code block: ~~~ @@ -123,7 +123,7 @@ class TestHeaderId(unittest.TestCase): def testBasicHeaderId(self): """ Test Basic HeaderID """ - + text = "# Some Header #" self.assertEqual(self.md.convert(text), '

Some Header

') @@ -189,8 +189,8 @@ The body. This is paragraph one.''' self.assertEqual(self.md.convert(text), '

The body. This is paragraph one.

') self.assertEqual(self.md.Meta, - {'author': ['Waylan Limberg', 'John Doe'], - 'blank_data': [''], + {'author': ['Waylan Limberg', 'John Doe'], + 'blank_data': [''], 'title': ['A Test Doc.']}) def testMissingMetaData(self): @@ -226,18 +226,18 @@ class TestWikiLinks(unittest.TestCase): def testSimpleSettings(self): """ Test Simple Settings. """ - self.assertEqual(markdown.markdown(self.text, + self.assertEqual(markdown.markdown(self.text, ['wikilinks(base_url=/wiki/,end_url=.html,html_class=foo)']), '

Some text with a ' 'WikiLink.

') - + def testComplexSettings(self): """ Test Complex Settings. """ md = markdown.Markdown( - extensions = ['wikilinks'], + extensions = ['wikilinks'], extension_configs = {'wikilinks': [ - ('base_url', 'http://example.com/'), + ('base_url', 'http://example.com/'), ('end_url', '.html'), ('html_class', '') ]}, safe_mode = True) @@ -268,8 +268,44 @@ Some text with a [[WikiLink]].""" def my_url_builder(label, base, end): return '/bar/' - md = markdown.Markdown(extensions=['wikilinks'], + md = markdown.Markdown(extensions=['wikilinks'], extension_configs={'wikilinks' : [('build_url', my_url_builder)]}) self.assertEqual(md.convert('[[foo]]'), '

foo

') +class TestAdmonition(unittest.TestCase): + """ Test Admonition Extension. """ + + def setUp(self): + self.md = markdown.Markdown(extensions=['admonition']) + self.text = \ +'''!!! note + First line + +!!! didyouknow "Did you know?" + Another text''' + + def testComplexSettings(self): + """ Test Complex Settings. """ + + # config = { + # 'styles': { + # 'note': ('note', 'Please Note'), + # 'didyouknow': ('note', 'Did you know?'), + # } + # } + + md = markdown.Markdown( + extensions=['admonition'], + extension_configs={ + 'admonition': [] + }, + safe_mode=True) + self.assertEqual(md.convert(self.text), + '
\n' + '

Note

\n' + '

First line

\n' + '
\n' + '
\n' + '

Did you know?

\n' + '

Another text

\n
') -- cgit v1.2.3 From bcfe4257299034eed6aae8351d115c7691db3a3e Mon Sep 17 00:00:00 2001 From: Tiago Serafim Date: Sat, 8 Sep 2012 09:00:57 -0300 Subject: Removed the configs. --- markdown/extensions/admonition.py | 55 ++++++++++++--------------------------- tests/test_extensions.py | 11 +------- 2 files changed, 17 insertions(+), 49 deletions(-) diff --git a/markdown/extensions/admonition.py b/markdown/extensions/admonition.py index d8a95d3..32f2038 100644 --- a/markdown/extensions/admonition.py +++ b/markdown/extensions/admonition.py @@ -7,15 +7,14 @@ Admonition extension for Python-Markdown Adds rST-style admonitions. Inspired by [rST][] feature with the same name. The syntax is (followed by an indented block with the contents): - !!! [optional title] + !!! [title] -Where `type` is one of the followings: - attention, caution, danger, error, hint, important, note, tip, warning +Where `type` is used as a CSS class name of the div. If not present, `title` +defaults to the capitalized `type`, so "note" -> "Note". -The above types have the appropriated title by default (i.e: note => Note) +rST suggests the following `types`, but you're free to use whatever you want: + attention, caution, danger, error, hint, important, note, tip, warning -It's also possible to create custom types (with default CSS classes and Titles) -see the docs for more info. A simple example: !!! note @@ -47,34 +46,16 @@ import re import markdown from markdown.util import etree -DEFAULT_STYLES = { - # 'id': ('CSS_class', 'Display Name') - 'attention': ('attention', 'Attention'), - 'caution': ('caution', 'Caution'), - 'danger': ('danger', 'Danger'), - 'error': ('error', 'Error'), - 'hint': ('hint', 'Hint'), - 'important': ('important', 'Important'), - 'note': ('note', 'Note'), - 'tip': ('tip', 'Tip'), - 'warning': ('warning', 'Warning'), -} - class AdmonitionExtension(markdown.Extension): """ Admonition extension for Python-Markdown. """ - def __init__(self, configs): - self.config = { - 'styles': DEFAULT_STYLES.copy(), - } - def extendMarkdown(self, md, md_globals): """ Add Admonition to Markdown instance. """ md.registerExtension(self) md.parser.blockprocessors.add('admonition', - AdmonitionProcessor(md.parser, self.config), + AdmonitionProcessor(md.parser), '_begin') @@ -84,9 +65,8 @@ class AdmonitionProcessor(markdown.blockprocessors.BlockProcessor): CLASSNAME_TITLE = 'admonition-title' RE = re.compile(r'(?:^|\n)!!!\ ?([\w\-]+)(?:\ "?([^"\n]+)"?)?') - def __init__(self, parser, config): + def __init__(self, parser): markdown.blockprocessors.BlockProcessor.__init__(self, parser) - self.config = config def test(self, parent, block): sibling = self.lastChild(parent) @@ -105,13 +85,12 @@ class AdmonitionProcessor(markdown.blockprocessors.BlockProcessor): block, theRest = self.detab(block) if m: - klass, title = self.get_class_and_title(m.group(1), m.group(2)) + klass, title = self.get_class_and_title(m) div = etree.SubElement(parent, 'div') div.set('class', u'%s %s' % (self.CLASSNAME, klass)) - if title: - p = etree.SubElement(div, 'p') - p.text = title - p.set('class', self.CLASSNAME_TITLE) + p = etree.SubElement(div, 'p') + p.text = title + p.set('class', self.CLASSNAME_TITLE) else: div = sibling @@ -123,13 +102,11 @@ class AdmonitionProcessor(markdown.blockprocessors.BlockProcessor): # list for future processing. blocks.insert(0, theRest) - def get_class_and_title(self, klass, title): - styles = self.config['styles'] - style = styles.get(klass, None) - if style: - return style[0], title or style[1] - else: - return klass, title + def get_class_and_title(self, match): + klass, title = match.group(1), match.group(2) + if not title: + title = klass.capitalize() + return klass, title def makeExtension(configs={}): diff --git a/tests/test_extensions.py b/tests/test_extensions.py index ca1520e..78c6d9d 100644 --- a/tests/test_extensions.py +++ b/tests/test_extensions.py @@ -288,18 +288,9 @@ class TestAdmonition(unittest.TestCase): def testComplexSettings(self): """ Test Complex Settings. """ - # config = { - # 'styles': { - # 'note': ('note', 'Please Note'), - # 'didyouknow': ('note', 'Did you know?'), - # } - # } - md = markdown.Markdown( extensions=['admonition'], - extension_configs={ - 'admonition': [] - }, + extension_configs={}, safe_mode=True) self.assertEqual(md.convert(self.text), '
\n' -- cgit v1.2.3 From 9756cb9f6014347179a9acf54a739aad5dda0c6d Mon Sep 17 00:00:00 2001 From: Tiago Serafim Date: Wed, 19 Sep 2012 18:37:02 -0300 Subject: More tests for the extension and new tests for the RE. It's now possible to use an explicit blank title to not have the

tag with the title rendered. --- markdown/extensions/admonition.py | 18 +++++++++--------- tests/extensions/admonition.html | 11 +++++++++++ tests/extensions/admonition.txt | 11 +++++++++++ tests/test_extensions.py | 30 +++++++++--------------------- 4 files changed, 40 insertions(+), 30 deletions(-) diff --git a/markdown/extensions/admonition.py b/markdown/extensions/admonition.py index 32f2038..0f6af80 100644 --- a/markdown/extensions/admonition.py +++ b/markdown/extensions/admonition.py @@ -7,7 +7,7 @@ Admonition extension for Python-Markdown Adds rST-style admonitions. Inspired by [rST][] feature with the same name. The syntax is (followed by an indented block with the contents): - !!! [title] + !!! [type] [optional explicit title] Where `type` is used as a CSS class name of the div. If not present, `title` defaults to the capitalized `type`, so "note" -> "Note". @@ -63,10 +63,7 @@ class AdmonitionProcessor(markdown.blockprocessors.BlockProcessor): CLASSNAME = 'admonition' CLASSNAME_TITLE = 'admonition-title' - RE = re.compile(r'(?:^|\n)!!!\ ?([\w\-]+)(?:\ "?([^"\n]+)"?)?') - - def __init__(self, parser): - markdown.blockprocessors.BlockProcessor.__init__(self, parser) + RE = re.compile(r'(?:^|\n)!!!\ ?([\w\-]+)(?:\ "(.*?)")?') def test(self, parent, block): sibling = self.lastChild(parent) @@ -88,9 +85,10 @@ class AdmonitionProcessor(markdown.blockprocessors.BlockProcessor): klass, title = self.get_class_and_title(m) div = etree.SubElement(parent, 'div') div.set('class', u'%s %s' % (self.CLASSNAME, klass)) - p = etree.SubElement(div, 'p') - p.text = title - p.set('class', self.CLASSNAME_TITLE) + if title: + p = etree.SubElement(div, 'p') + p.text = title + p.set('class', self.CLASSNAME_TITLE) else: div = sibling @@ -104,8 +102,10 @@ class AdmonitionProcessor(markdown.blockprocessors.BlockProcessor): def get_class_and_title(self, match): klass, title = match.group(1), match.group(2) - if not title: + if title is None: title = klass.capitalize() + elif title == '': + title = None return klass, title diff --git a/tests/extensions/admonition.html b/tests/extensions/admonition.html index f28bcfd..437cac6 100644 --- a/tests/extensions/admonition.html +++ b/tests/extensions/admonition.html @@ -6,6 +6,14 @@

  • first
  • second
    • +
    +

    Some important quote

    +

    another paragraph in the quote

    +
    +
    int main() {
+    // insert some code
+}
+

    More text and stuff.

    @@ -16,4 +24,7 @@

    And now...

    For something completely different.

    You can also use a custom CSS class name.

    +
    +
    +

    An explicitly empty string prevents the title from being rendered.

    \ No newline at end of file diff --git a/tests/extensions/admonition.txt b/tests/extensions/admonition.txt index e8db239..fd18bd6 100644 --- a/tests/extensions/admonition.txt +++ b/tests/extensions/admonition.txt @@ -6,6 +6,14 @@ Some text 1. first 2. second + > Some important quote + + > another paragraph in the quote + + int main() { + // insert some code + } + More text and stuff. !!! note "Did you know?" @@ -15,3 +23,6 @@ More text and stuff. For something completely different. You can also use a custom CSS class name. + +!!! tip "" + An explicitly empty string prevents the title from being rendered. diff --git a/tests/test_extensions.py b/tests/test_extensions.py index 78c6d9d..7661347 100644 --- a/tests/test_extensions.py +++ b/tests/test_extensions.py @@ -278,25 +278,13 @@ class TestAdmonition(unittest.TestCase): def setUp(self): self.md = markdown.Markdown(extensions=['admonition']) - self.text = \ -'''!!! note - First line -!!! didyouknow "Did you know?" - Another text''' - - def testComplexSettings(self): - """ Test Complex Settings. """ - - md = markdown.Markdown( - extensions=['admonition'], - extension_configs={}, - safe_mode=True) - self.assertEqual(md.convert(self.text), - '
    \n' - '

    Note

    \n' - '

    First line

    \n' - '
    \n' - '
    \n' - '

    Did you know?

    \n' - '

    Another text

    \n
    ') + def testRE(self): + RE = self.md.parser.blockprocessors['admonition'].RE + tests = [ + ('!!! note', ('note', None)), + ('!!! note "Please Note"', ('note', 'Please Note')), + ('!!! note ""', ('note', '')), + ] + for test, expected in tests: + self.assertEqual(RE.match(test).groups(), expected) -- cgit v1.2.3 From 85e74fb710e64a35b3ed458bdec6cfed7827c3b1 Mon Sep 17 00:00:00 2001 From: Tiago Serafim Date: Wed, 19 Sep 2012 18:43:21 -0300 Subject: First version of the docs. --- docs/extensions/admonition.txt | 75 ++++++++++++++++++++++++++++++++++++++++ docs/extensions/code_hilite.txt | 46 ++++++++++++------------ docs/extensions/index.txt | 25 +++++++------- docs/extensions/smart_strong.txt | 6 ++-- 4 files changed, 114 insertions(+), 38 deletions(-) create mode 100644 docs/extensions/admonition.txt diff --git a/docs/extensions/admonition.txt b/docs/extensions/admonition.txt new file mode 100644 index 0000000..48b70c8 --- /dev/null +++ b/docs/extensions/admonition.txt @@ -0,0 +1,75 @@ +title: Admonition +prev_title: Smart Strong Extension +prev_url: smart_strong.html +next_title: CodeHilite Extension +next_url: code_hilite.html + +Admonition +========== + +Summary +------- + +This extension adds [rST-style][rST] admonitions to Markdown documents. + +This extension is included in the standard Markdown library. + +[rST]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#specific-admonitions + +Syntax +------ + +Admonitions are created using the following syntax: + + !!! [type] [optional explicit title within double quotes] + Any number of other indented markdown elements. + + This is the second paragraph. + +`type` will be used as the CSS classname and as default title. It must be a +single word. So, for instance: + + !!! note + You should note that the title will be automatically capitalized. + +will render: + +
    +

    Note

    +

    You should note that the title will be automatically capitalized.

    +
    + +Optionally, you can use custom titles. For instance: + + !!! danger "Don't try this at home" + ... + +will render: + +
    +

    Don't try this at home

    +

    ...

    +
    + +If you don't want a title, use a blank string `""`: + + !!! important "" + This is a admonition box without a title. + +results in: + +
    +

    This is a admonition box without a title.

    +
    + + +rST suggests the following `types`, but you're free to use whatever you want: + attention, caution, danger, error, hint, important, note, tip, warning. + +Styling +------- + +There is no CSS included as part of this extension. Look up the default +[Sphinx][sphinx] theme if you need inspiration. + +[sphinx]: http://sphinx.pocoo.org/ \ No newline at end of file diff --git a/docs/extensions/code_hilite.txt b/docs/extensions/code_hilite.txt index 55a1a00..fbf05b3 100644 --- a/docs/extensions/code_hilite.txt +++ b/docs/extensions/code_hilite.txt @@ -1,6 +1,6 @@ title: CodeHilite Extension -prev_title: Smart Strong Extension -prev_url: smart_strong.html +prev_title: Admonition Extension +prev_url: admonition.html next_title: HTML Tidy Extension next_url: html_tidy.html @@ -10,7 +10,7 @@ CodeHilite Summary ------- -The CodeHilite Extension adds code/syntax highlighting to standard +The CodeHilite Extension adds code/syntax highlighting to standard Python-Markdown code blocks using [Pygments][]. [Pygments]: http://pygments.org/ @@ -20,32 +20,32 @@ This extension is included in the Markdown library. Setup ----- -You will also need to [download][dl] and install the Pygments package on your +You will also need to [download][dl] and install the Pygments package on your `PYTHONPATH`. You will need to determine the appropriate CSS classes and create -appropriate rules for them, which are either defined in or linked from the -header of your HTML templates. See the excellent [documentation][] for more -details. If no language is defined, Pygments will attempt to guess the +appropriate rules for them, which are either defined in or linked from the +header of your HTML templates. See the excellent [documentation][] for more +details. If no language is defined, Pygments will attempt to guess the language. When that fails, the code block will display as un-highlighted code. [dl]: http://pygments.org/download/ [documentation]: http://pygments.org/docs -**Note:** The css and/or javascript is not included as part of this extension +**Note:** The css and/or javascript is not included as part of this extension but shall always be provided by the end user. Syntax ------ -The CodeHilite Extension follows the same [syntax][] as regular Markdown code -blocks, with one exception. The hiliter needs to know what language to use for -the code block. There are three ways to tell the hiliter what language the code +The CodeHilite Extension follows the same [syntax][] as regular Markdown code +blocks, with one exception. The hiliter needs to know what language to use for +the code block. There are three ways to tell the hiliter what language the code block contains and each one has a different result. [syntax]: http://daringfireball.net/projects/markdown/syntax#precode ###SheBang (with path) -If the first line of the codeblock contains a shebang, the language is derived +If the first line of the codeblock contains a shebang, the language is derived from that and line numbers are used. #!/usr/bin/python @@ -59,8 +59,8 @@ Will result in: ###SheBang (no path) -If the first line contains a shebang, but the shebang line does not contain a -path (a single `/` or even a space), then that line is removed from the code +If the first line contains a shebang, but the shebang line does not contain a +path (a single `/` or even a space), then that line is removed from the code block before processing. Line numbers are used. #!python @@ -72,8 +72,8 @@ Will result in: ####Colons -If the first line begins with three or more colons, the text following the -colons identifies the language. The first line is removed from the code block +If the first line begins with three or more colons, the text following the +colons identifies the language. The first line is removed from the code block before processing and line numbers are not used. :::python @@ -85,10 +85,10 @@ Will result in: ###When No Language is Defined -CodeHilite is completely backward compatible so that if a code block is -encountered that does not define a language, the block is simple wrapped in -`
    ` tags and output. Note: one exception would be that the Pygments 
-highlighting engine will try to guess the language. Upon failure, the same 
+CodeHilite is completely backward compatible so that if a code block is
+encountered that does not define a language, the block is simple wrapped in
+`
    ` tags and output. Note: one exception would be that the Pygments
+highlighting engine will try to guess the language. Upon failure, the same
 behavior will happen as described here.
 
         # Code goes here ...
@@ -109,11 +109,11 @@ From the Python interpreter:
 
     >>> html = markdown.markdown(text, ['codehilite'])
 
-If you want every code block to have line numbers, even when using colons 
-(`:::`) for language identification, the setting `force_linenos` is available 
+If you want every code block to have line numbers, even when using colons
+(`:::`) for language identification, the setting `force_linenos` is available
 to do so.
 
-    >>> html = markdown.markdown(text, 
+    >>> html = markdown.markdown(text,
     ...     ['codehilite(force_linenos=True)']
     ... )
 
diff --git a/docs/extensions/index.txt b/docs/extensions/index.txt
index 82b0eda..610fe21 100644
--- a/docs/extensions/index.txt
+++ b/docs/extensions/index.txt
@@ -8,16 +8,16 @@ next_url:   extra.html
 Available Extensions
 ====================
 
-Python Markdown offers a flexible extension mechanism, which makes it possible 
-to change and/or extend the behavior of the parser without having to edit the 
-actual source files. 
+Python Markdown offers a flexible extension mechanism, which makes it possible
+to change and/or extend the behavior of the parser without having to edit the
+actual source files.
 
 To use an extension, pass it's name to markdown with the `extensions` keyword.
-See the [Library Reference](../reference.html#extensions) for more details. 
+See the [Library Reference](../reference.html#extensions) for more details.
 
     markdown.markdown(some_text, extensions=['extra', 'nl2br'])
 
-From the command line, specify an extension with the `-x` option. See the 
+From the command line, specify an extension with the `-x` option. See the
 [Command Line docs](../cli.html) or use the `--help` option for more details.
 
     python -m markdown -x extra input.txt > output.html
@@ -26,9 +26,9 @@ Officially Supported Extensions
 -------------------------------
 
 The extensions listed below are included with (at least) the most recent release
-and are officially supported by Python-Markdown. Any documentation is 
-maintained here and all bug reports should be made to the project. If you 
-have a typical install of Python-Markdown, these extensions are already 
+and are officially supported by Python-Markdown. Any documentation is
+maintained here and all bug reports should be made to the project. If you
+have a typical install of Python-Markdown, these extensions are already
 available to you.
 
 * [Extra](extra.html)
@@ -39,6 +39,7 @@ available to you.
     * [Footnotes](footnotes.html)
     * [Tables](tables.html)
     * [Smart Strong](smart_strong.html)
+* [Admonition](admonition.html)
 * [CodeHilite](code_hilite.html)
 * [HTML Tidy](html_tidy.html)
 * [HeaderId](header_id.html)
@@ -53,11 +54,11 @@ Third Party Extensions
 ----------------------
 
 Various individuals and/or organizations have developed extensions which they
-have made available to the public.  A [list of third party 
+have made available to the public.  A [list of third party
 extensions](https://github.com/waylan/Python-Markdown/wiki/Third-Party-Extensions)
-is maintained on the wiki for your convenience. The Python-Markdown team 
-offers no official support for these extensions. Please see the developer of 
+is maintained on the wiki for your convenience. The Python-Markdown team
+offers no official support for these extensions. Please see the developer of
 each extension for support.
 
-If you would like to write your own extensions, see the 
+If you would like to write your own extensions, see the
 [Extensions API](api.html) for details.
diff --git a/docs/extensions/smart_strong.txt b/docs/extensions/smart_strong.txt
index 8de574f..fd3bae6 100644
--- a/docs/extensions/smart_strong.txt
+++ b/docs/extensions/smart_strong.txt
@@ -1,8 +1,8 @@
 title:      Smart Strong Extension
 prev_title: Tables Extension
 prev_url:   tables.html
-next_title: CodeHilite Extension
-next_url:   code_hilite.html
+next_title: Admonition Extension
+next_url:   admonition.html
 
 Smart_Strong
 ============
@@ -11,7 +11,7 @@ Summary
 -------
 
 The Markdown Smart_Strong Extension adds smarter handling of double underscores
-within words. This does for double underscores what 
+within words. This does for double underscores what
 [smart_emphasis](../reference.html#smart_emphasis) does for single underscores.
 
 The Smart_Strong Extension is included in the standard Markdown library.
-- 
cgit v1.2.3


From 6c15c64df40b9ded3f5dea2e694905222791c1b6 Mon Sep 17 00:00:00 2001
From: Tiago Serafim 
Date: Wed, 19 Sep 2012 19:42:00 -0300
Subject: Added comments detailing the difference between not providing a title
 and using a blank string as a title

---
 markdown/extensions/admonition.py | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/markdown/extensions/admonition.py b/markdown/extensions/admonition.py
index 0f6af80..798befb 100644
--- a/markdown/extensions/admonition.py
+++ b/markdown/extensions/admonition.py
@@ -103,8 +103,12 @@ class AdmonitionProcessor(markdown.blockprocessors.BlockProcessor):
     def get_class_and_title(self, match):
         klass, title = match.group(1), match.group(2)
         if title is None:
+            # no title was provided, use the capitalized classname as title
+            # e.g.: `!!! note` will render `
    Note
    `
             title = klass.capitalize()
         elif title == '':
+            # an explicit blank title should not be rendered
+            # e.g.: `!!! warning ""` will *not* render `p` with a title
             title = None
         return klass, title
 
-- 
cgit v1.2.3


From f78dcbedf94baa17392dafd5bb08c47d2a57ba74 Mon Sep 17 00:00:00 2001
From: Tiago Serafim 
Date: Sat, 9 Feb 2013 17:45:03 -0200
Subject: Better synthax description in the docs.

---
 docs/extensions/admonition.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/extensions/admonition.txt b/docs/extensions/admonition.txt
index 48b70c8..21a16f4 100644
--- a/docs/extensions/admonition.txt
+++ b/docs/extensions/admonition.txt
@@ -21,7 +21,7 @@ Syntax
 
 Admonitions are created using the following syntax:
 
-    !!! [type] [optional explicit title within double quotes]
+    !!! type "optional explicit title within double quotes"
         Any number of other indented markdown elements.
 
         This is the second paragraph.
-- 
cgit v1.2.3