diff options
Diffstat (limited to 'docs/cli.txt')
| -rw-r--r-- | docs/cli.txt | 58 |
1 files changed, 52 insertions, 6 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/ |