Markdown Abbreviation Extension achinghead.com

Summary

The Markdown Abbreviation Extension is an extension to the Python implementation of Markdown that adds the ability to define abbreviations. Specifically, any defined abbreviation is wrapped in an <abbr> tag.

Get the Code

You can view or download the latest from trunk.

Previous Versions

(first public release)

Dependencies

Python 2.3+
Markdown 1.6+ (a known incompatibility exists with Markdown 1.6b. See the bug report and patch for details.)
Meta-Data Extension (optional)

License

The Markdown Abbreviation Extension is licensed under the BSD License.

Syntax

There are three ways to define abbreviation definitions; inline, by reference, and from an external source.

Inline Abbreviations

Abbreviations can be defined inline like this:

Some text with an [ABBR]{Abbreviation}.

Which will be rendered as:

<p>Some text with  an <abbr title="Abbreviation">ABBR</abbr>.
</p>

Abbreviations By Reference

Abbreviations can also be defined in the syntax established in PHP Markdown Extra.

Thus, the following text (taken from the above referenced PHP documentation):

The HTML specification 
is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]:  World Wide Web Consortium

will be rendered like so:

<p>The <abbr title="Hyper Text Markup Language">HTML</abbr> specification 
   is maintained by the <abbr title="World Wide Web Consortium">W3C</abbr>.
</p>

Abbreviations Externally Defined

Abbreviations can also be defined outside of the instant document and passed in, either as a python dict through config settings or from external text files.

Defining Abbreviations in Python

If you have a python dictionary of abbreviation definitions, they can be passed in through Markdown's extension_configs interface with the abbrs setting. Note the following example:

>>> md = markdown.Markdown(text, 
...     extensions = ['abbr'], 
...     extension_configs = {'abbr': [('abbrs', {'HTML' : 'Hypertext Markup Language',
...                                              'W3C' : 'World Wide Web Consortium'})]}, 
...     encoding='utf-8',
...     safe_mode = True)

Defining Abbreviations in External Files

External text files should contain abbreviation definitions in the same reference format as described above; one definition per line. Any lines not matching the definitions syntax are ignored. In fact, any markdown document containing abbreviation references could easily serve as an external source file. See an example (raw).

There are currently two ways of specifying the external files. In each case, the file path is assumed to start in the cwd (current working directory) of the python instance unless explicitly given from root. Basically, the file pointer should be the same as the string one would pass to python's open method. If a file cannot be found, it gives up silently, and no error is generated.

External File Through Settings

The external file can be pointed to through the file setting as the following example demonstrates:

>>> md = markdown.Markdown(text, 
...     extensions = ['abbr'],
...     extension_configs = {'abbr': [('file', 'abbr.txt')]},
...     encoding='utf-8')

External Files through Meta-Data

The Abbreviation Extension also supports the Meta-Data Extension. Please see the documentation for that extension for specifics. The only supported meta-data keyword is abbr_files. The following example will define two files which provide abbreviation definitions:
```
Abbr_Files: general_abbrs.txt
            web_abbrs.txt
```

Precedence

From time to time more that one definition of the same abbreviation may be defined for one document. Obviously, inline definitions are not effected (although there is a bug even with my patch to markdown 1.6b). All other definitions are processed in the following order with the last instance of the definition being used through the entire document:

Python Dict defined through extension_configs.
External file defined through extension_configs.
External files defined through Meta-Data from first to last.
References defined within the document from top to bottom.

Usage

From the Python interpreter:

>>> import markdown
>>> text = """
... Some text with an ABBR.
...
... *[ABBR]: Abbreviation
... """
>>> md = markdown.markdown(text, ['abbr'])
>>> html = str(md)

To use with other extensions, just add them to the list, like this:

>>> md = markdown.markdown(text, ['abbr', 'footnotes'])

Abbreviations can also be called from the command line using Markdown's -x parameter, like so:

python markdown.py -x abbr source.txt > output.html

Misc

You can test the syntax in the dingus. 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).

achinghead.com