aboutsummaryrefslogtreecommitdiffstats
path: root/docs/cli.txt
diff options
context:
space:
mode:
Diffstat (limited to 'docs/cli.txt')
-rw-r--r--docs/cli.txt58
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/