diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/cli.txt | 58 | ||||
| -rw-r--r-- | docs/release-2.5.txt | 31 |
2 files changed, 73 insertions, 16 deletions
diff --git a/docs/cli.txt b/docs/cli.txt index ff19501..f805b5e 100644 --- a/docs/cli.txt +++ b/docs/cli.txt @@ -112,13 +112,59 @@ For a complete list of options, run Using Extensions ---------------- -For an extension to be run from the command line it must be provided in a module -on your python path (see the [Extension API](extensions/api.html) for details). -It can then be invoked by the name of that module: +To load a Python-Markdown extension from the command line use the `-x` +(or `--extension`) option. For extensions included with Python-Markdown, use +the short "Name" [documented] for that extension. - $ markdown_py -x footnotes text_with_footnotes.txt > output.html +[documented]: index.html#officially-supported-extensions -If the extension supports config options, you can pass them in as well: + $ python -m markdown -x footnotes text_with_footnotes.txt - $ markdown_py -x "footnotes(PLACE_MARKER=~~~~~~~~)" input.txt +For third party extensions, the extension module must be on your `PYTHONPATH` +(see the [Extension API](extensions/api.html) for details). The extension can +then be invoked by the name of that module using Python's dot syntax: + + $ python -m markdown -x path.to.module input.txt + +To load multiple extensions, specify an `-x` option for each extension: + + $ python -m markdown -x footnotes -x codehilite input.txt + +If the extension supports configuration options (see the documentation for the +extension you are using to determine what settings it supports, if any), you +can pass them in as well: + + $ python -m markdown -x footnotes -c config.yml input.txt + +The `-c` (or `--extension_configs`) option accepts a file name. The file must be in +either the [YAML] or [JSON] format and contain YAML or JSON data that would map to +a Python Dictionary in the format required by the [`extension_configs`][ec] keyword +of the `markdown.Markdown` class. Therefore, the file `config.yaml` referenced in the +above example might look like this: + + footnotes: + PLACE_MARKER: ~~~~~~~~ + UNIQUE_IDS: True + +Note that while the `--extension_configs` option does specify the "footnotes" extension, +you still need to load the extension with the `-x` option, or the configs for that +extension will be ignored. + +The `--extension_configs` option will only support YAML config files if [PyYaml] is +installed on your system. JSON should work with no additional dependencies. The format +of your config file is automatically detected. + +As an alternative, you may append the extension configs as a string to the extension name +that is provided to the `-x-` option in the following format: + + $ python -m markdown -x "footnotes(PLACE_MARKER=~~~~~~~~,UNIQUE_IDS=1)" input.txt + +Note that there are no quotes or whitespace in the above format, which severely limits +how it can be used. For more complex settings, it is suggested that the +`--extension_configs` option be used. + +[ec]: reference.html#extension_configs +[YAML]: http://yaml.org/ +[JSON]: http://json.org/ +[PyYAML]: http://pyyaml.org/ diff --git a/docs/release-2.5.txt b/docs/release-2.5.txt index 1ff0eff..4f8526f 100644 --- a/docs/release-2.5.txt +++ b/docs/release-2.5.txt @@ -20,14 +20,6 @@ Backwards-incompatible Changes What's New in Python-Markdown 2.5 --------------------------------- -* The Extension Configuration code has been refactord to make it a little easier -for extension authors to work with config settings. As a result, the -[extension_configs] keyword now accepts a dictionary rather than requiring -a list of tuples. A list of tuples is still supported so no one needs to change -their existing code. This should simplify the learning curve for new users. - -[extension_configs]: reference.html#extension_configs - * The [Smarty Extension] has had a number of additional configuration settings added, which allows one to define their own sustitutions to better support languages other than English. Thanks to [Martin Altmayer] for implementing this feature. @@ -35,8 +27,27 @@ languages other than English. Thanks to [Martin Altmayer] for implementing this [Smarty Extension]: extensions/smarty.html [Martin Altmayer]:https://github.com/MartinAltmayer -There have been various refactors of the testing framework. While those changes -will not directly effect end users, the code is being better tested whuch will +* The Extension Configuration code has been refactord to make it a little easier +for extension authors to work with config settings. As a result, the +[`extension_configs`][ec] keyword now accepts a dictionary rather than requiring +a list of tuples. A list of tuples is still supported so no one needs to change +their existing code. This should also simplify the learning curve for new users. + +[ec]: reference.html#extension_configs + +* The [Command Line Interface][cli] now accepts a `--extensions_config` (or `-c`) option +which accepts a filename and passes the parsed content of a [YAML] or [JSON] file to the +[`extension_configs`][ec] keyword of the `markdown.Markdown` class. The conetents of +the YAML or JSON must map to a Python Dictionary which matches the format required +by the `extension_configs` kerword. Note that [PyYAML] is required to parse YAML files. + +[cli]: cli.html#using-extensions +[YAML]: http://yaml.org/ +[JSON]: http://json.org/ +[PyYAML]: http://pyyaml.org/ + +* There have been various refactors of the testing framework. While those changes +will not directly effect end users, the code is being better tested which will benefit everyone. * Various bug fixes have been made. See the |