diff options
Diffstat (limited to 'docs/extensions')
| -rw-r--r-- | docs/extensions/abbreviations.txt | 2 | ||||
| -rw-r--r-- | docs/extensions/api.txt | 62 | ||||
| -rw-r--r-- | docs/extensions/attr_list.txt | 12 | ||||
| -rw-r--r-- | docs/extensions/code_hilite.txt | 30 | ||||
| -rw-r--r-- | docs/extensions/definition_lists.txt | 4 | ||||
| -rw-r--r-- | docs/extensions/extra.txt | 5 | ||||
| -rw-r--r-- | docs/extensions/index.txt | 79 | ||||
| -rw-r--r-- | docs/extensions/wikilinks.txt | 6 |
8 files changed, 103 insertions, 97 deletions
diff --git a/docs/extensions/abbreviations.txt b/docs/extensions/abbreviations.txt index fa38f50..21d90bf 100644 --- a/docs/extensions/abbreviations.txt +++ b/docs/extensions/abbreviations.txt @@ -56,4 +56,4 @@ To use with other extensions, just add them to the list, like this: Abbreviations can also be called from the command line using Markdown's `-x` parameter, like so: - markdown.py -x abbr source.txt > output.html + python -m markdown -x abbr source.txt > output.html diff --git a/docs/extensions/api.txt b/docs/extensions/api.txt index 69fb68e..ac840f9 100644 --- a/docs/extensions/api.txt +++ b/docs/extensions/api.txt @@ -562,27 +562,10 @@ values, and should be converted at run time. For example: ### makeExtension {: #makeextension } -Each extension should ideally be placed in its own module starting -with the ``mdx_`` prefix (e.g. ``mdx_footnotes.py``). The module must -provide a module-level function called ``makeExtension`` that takes -an optional parameter consisting of a dictionary of configuration over-rides -and returns an instance of the extension. An example from the footnote -extension: - - def makeExtension(configs=None) : - return FootnoteExtension(configs=configs) - -By following the above example, when Markdown is passed the name of your -extension as a string (i.e.: ``'footnotes'``), it will automatically import -the module and call the ``makeExtension`` function initiating your extension. +As noted in the [library reference] an instance of an extension can be passed +directly to Markdown. In fact, this is the prefered way to use third-party +extensions. -You may have noted that the extensions packaged with Python-Markdown do not -use the ``mdx_`` prefix in their module names. This is because they are all -part of the ``markdown.extensions`` package. Markdown will first try to import -from ``markdown.extensions.extname`` and upon failure, ``mdx_extname``. If both -fail, Markdown will continue without the extension. - -However, Markdown will also accept an already existing instance of an extension. For example: import markdown @@ -591,8 +574,42 @@ For example: myext = myextension.MyExtension(configs=configs) md = markdown.Markdown(extensions=[myext]) -This is useful if you need to implement a large number of extensions with more -than one residing in a module. +This is especially useful if you need to implement a large number of extensions +with more than one residing in a module. + +However, for historical reasons, Markdown also accepts "named" third party +extensions. In that case, only one extension can be defined per module +and that extension must define a module-level function called +`makeExtension` that takes an optional parameter consisting of a dictionary +of configuration over-rides and returns an instance of the extension. For example: + + class MyExtension(markdown.extensions.Extension) + # Define extension here... + + def makeExtension(configs=None): + return MyExtension(configs=configs) + +When Markdown is passed the "name" of your extension as a string, it will import +the module and call the `makeExtension` function to initiate your extension. + +The "name" of your extension must be a string consisting of the importable path to +your module using Python's dot notation. Therefore, if you are providing a library +to your users and would like to include a custom markdown extensions with your +library, that extension would be named `"mylib.mdext.myext"` where `mylib/mdext/myext.py` +contains the `makeExtension` function and the `mylib` directory is on the PYTHONPATH. + +You may have noted that the extensions packaged with Python-Markdown do not +use Python's dot notation in their names. This is because they are +all part of the `markdown.extensions` package. If a "name" contains any dots +(`.`), then it will be imported as-is. Otherwise, Markdown will first try to +import from `markdown.extensions.extname` and upon failure, `mdx_extname` where +`"extname"` is the "name" passed to Markdown. + +!!! Note + While the `mdx_extname` method of naming extensions is still supported, it + remains solely for historical reasons to support the various existing + third-party extensions. This method is discouraged going forward and support + may be removed in a future release. [Preprocessors]: #preprocessors [InlinePatterns]: #inlinepatterns @@ -610,3 +627,4 @@ than one residing in a module. [Available Extensions]: index.html [Footnotes]: footnotes.html [Definition Lists]: definition_lists.html +[library reference]: ../reference.html diff --git a/docs/extensions/attr_list.txt b/docs/extensions/attr_list.txt index 4134a82..54a61d0 100644 --- a/docs/extensions/attr_list.txt +++ b/docs/extensions/attr_list.txt @@ -26,14 +26,14 @@ The basic syntax was inspired by [Maruku][]'s Attribute List feature. An example attribute list might look like this: - {: #someid .someclass somekey='some values' } + {: #someid .someclass somekey='some value' } -A word which starts with a hash `#` will set the id of an element. +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 word which starts with a dot (`.`) will be added to the list of classes +assigned to an element. -A key/value pair will assign that pair to the element. +A key/value pair (`somekey='some value'`) 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: @@ -42,7 +42,7 @@ will always override the previously defined attribute. Consider the following: The above example would result in the following attributes being defined: - id="id2 class="class2 class3 class4" + id="id2" class="class2 class3 class4" ### Block Level ### diff --git a/docs/extensions/code_hilite.txt b/docs/extensions/code_hilite.txt index 31ecfbb..57f81ca 100644 --- a/docs/extensions/code_hilite.txt +++ b/docs/extensions/code_hilite.txt @@ -30,8 +30,9 @@ 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 -but shall always be provided by the end user. +!!! Note + The css and/or javascript is not included as part of this extension + but shall always be provided by the end user. Syntax ------ @@ -42,11 +43,11 @@ the code block. There are three ways to tell the hiliter what language the code block contains and each one has a different result. !!! Note -The format of the language identifier only effects the display of line numbers -if `linenums` is set to `None` (the default). If set to `True` or `False` -(see [Usage](#usage) below) the format of the identifier has no effect on the -display of line numbers -- it only serves as a means to define the language -of the code block. + The format of the language identifier only effects the display of line numbers + if `linenums` is set to `None` (the default). If set to `True` or `False` + (see [Usage](#usage) below) the format of the identifier has no effect on the + display of line numbers -- it only serves as a means to define the language + of the code block. [syntax]: http://daringfireball.net/projects/markdown/syntax#precode @@ -93,10 +94,8 @@ 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 -`<pre>` 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. +encountered that does not define a language, the block is simply wrapped in +`<pre>` tags and output. # Code goes here ... @@ -106,9 +105,14 @@ Will result in: Lets see the source for that: - <div class="codehilite" ><pre><code># Code goes here ... + <div class="codehilite"><pre><code># Code goes here ... </code></pre></div> +!!! Note + When no language is defined, the Pygments highlighting engine will try to guess + the language (unless `guess_lang` is set to `False`). Upon failure, the same + behavior will happen as described above. + Usage ----- @@ -131,7 +135,7 @@ SheBangs (`#!`) for language identification, set `linenums` to `False`. ... ) If you want to prevent Pygments from guessing the language, only highlighting -blocks when you explicitly request it, set the `guess_lang` setting to 'False'. +blocks when you explicitly request it, set the `guess_lang` setting to `False`. >>> html = markdown.markdown(text, ... extensions=['codehilite(guess_lang=False)'] diff --git a/docs/extensions/definition_lists.txt b/docs/extensions/definition_lists.txt index 53f14a0..a5ba393 100644 --- a/docs/extensions/definition_lists.txt +++ b/docs/extensions/definition_lists.txt @@ -10,7 +10,7 @@ Definition Lists Summary ------- -The Definition List Extension adds the ability to create definition list in +The Definition List Extension adds the ability to create definition lists in Markdown documents. This extension is included in the standard Markdown library. @@ -58,4 +58,4 @@ To use with other extensions, just add them to the list, like this: The extension can also be called from the command line using Markdown's `-x` parameter: - markdown.py -x def_list source.txt > output.html + python -m markdown -x def_list source.txt > output.html diff --git a/docs/extensions/extra.txt b/docs/extensions/extra.txt index adafe07..d747496 100644 --- a/docs/extensions/extra.txt +++ b/docs/extensions/extra.txt @@ -34,11 +34,6 @@ From the Python interpreter: >>> import markdown >>> html = markdown.markdown(text, ['extra']) -In the unlikely event that one or more of the supported extensions are not -available for import, Markdown will simply continue without that -extension. If you would like to be notified of such failures, -you may set Python-Markdown's logger level to "WARN". - There may be [additional extensions](index.html) that are distributed with Python-Markdown that are not included here in Extra. The features of those extensions are not part of PHP Markdown Extra, and diff --git a/docs/extensions/index.txt b/docs/extensions/index.txt index 5cbdd7d..99ca8c7 100644 --- a/docs/extensions/index.txt +++ b/docs/extensions/index.txt @@ -12,16 +12,22 @@ 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. +To use an extension, pass it to markdown with the `extensions` keyword. + + markdown.markdown(some_text, extensions=[MyExtension(), 'path.to.my.ext', 'footnotes']) - markdown.markdown(some_text, extensions=['footnotes', 'nl2br']) +See the [Library Reference](../reference.html#extensions) for more details. -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. +From the command line, specify an extension with the `-x` option. python -m markdown -x footnotes -x tables input.txt > output.html +See the [Command Line docs](../cli.html) or use the `--help` option for more details. + +!!! seealso "See Also" + If you would like to write your own extensions, see the + [Extension API](api.html) for details. + Officially Supported Extensions ------------------------------- @@ -29,25 +35,29 @@ 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 -available to you. - -### Markdown Extra - -You can enable **all** these extensions just as if it was a single -`extra` extension. Example: - - markdown.markdown(some_text, extensions=['extra', 'codehilite']) - -Extension | Name in Python-Markdown ---------- | ----------------------- -[Abbreviations][] | `abbr` -[Attribute Lists][] | `attr_list` -[Definition Lists][] | `def_list` -[Fenced Code Blocks][] | `fenced_code` -[Footnotes][] | `footnotes` -[Tables][] | `tables` -[Smart Strong][] | `smart_strong` - +available to you using the "name" listed in the second column below. + +Extension | "Name" +------------------------------------ | --------------- +[Extra] | `extra` + [Abbreviations][] | `abbr` + [Attribute Lists][] | `attr_list` + [Definition Lists][] | `def_list` + [Fenced Code Blocks][] | `fenced_code` + [Footnotes][] | `footnotes` + [Tables][] | `tables` + [Smart Strong][] | `smart_strong` +[Admonition][] | `admonition` +[CodeHilite][] | `codehilite` +[HTML Tidy][] | `html_tidy` +[HeaderId] | `headerid` +[Meta-Data] | `meta` +[New Line to Break] | `nl2br` +[Sane Lists] | `sane_lists` +[Table of Contents] | `toc` +[WikiLinks] | `wikilinks` + +[Extra]: extra.html [Abbreviations]: abbreviations.html [Attribute Lists]: attr_list.html [Definition Lists]: definition_lists.html @@ -55,24 +65,6 @@ Extension | Name in Python-Markdown [Footnotes]: footnotes.html [Tables]: tables.html [Smart Strong]: smart_strong.html - -### Other extensions - -There are also some extensions that are not included in Markdown Extra -but come in the standard Python-Markdown library. - -Extension | Name in Python-Markdown ---------- | ----------------------- -[Admonition][] | `admonition` -[CodeHilite][] | `codehilite` -[HTML Tidy][] | `html_tidy` -[HeaderId] | `headerid` -[Meta-Data] | `meta` -[New Line to Break] | `nl2br` -[Sane Lists] | `sane_lists` -[Table of Contents] | `toc` -[WikiLinks] | `wikilinks` - [Admonition]: admonition.html [CodeHilite]: code_hilite.html [HTML Tidy]: html_tidy.html @@ -92,6 +84,3 @@ extensions](https://github.com/waylan/Python-Markdown/wiki/Third-Party-Extension 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 -[Extensions API](api.html) for details. diff --git a/docs/extensions/wikilinks.txt b/docs/extensions/wikilinks.txt index 5f6d20e..ed191e3 100644 --- a/docs/extensions/wikilinks.txt +++ b/docs/extensions/wikilinks.txt @@ -54,7 +54,7 @@ From the Python interpreter: The default behavior is to point each link to the document root of the current domain and close with a trailing slash. Additionally, each link is assigned to the html class `wikilink`. This may not always be desirable. Therefore, one can -customize that behavior within Python code. Three settings are provided to +customize that behavior within Python code. Four settings are provided to change the default behavior: 1. **base_url**: String to append to beginning of URL. @@ -108,7 +108,7 @@ Would cause all wikilinks to be assigned to the class `myclass`. The same options can be used on the command line as well: - python markdown.py -x wikilink(base_url=http://example.com/,end_url=.html,html_class=foo) src.txt + python -m markdown -x wikilink(base_url=http://example.com/,end_url=.html,html_class=foo) src.txt Some may prefer the more complex format when calling the `Markdown` class directly: @@ -133,7 +133,7 @@ meta-data keywords are: * `wiki_end_url` * `wiki_html_class` -When used, the meta-data will override the settings provided through the +When used, the meta-data will override the settings provided through the `extension_configs` interface. This document: |