diff options
author | Waylan Limberg <waylan.limberg@icloud.com> | 2018-01-12 22:48:41 -0500 |
---|---|---|
committer | GitHub <noreply@github.com> | 2018-01-12 22:48:41 -0500 |
commit | cd7324333a995eeb62a3e6eacdb3b179c6256133 (patch) | |
tree | d26faeb19e7ebee577df752e1c622ae15475ca42 /docs/cli.md | |
parent | d4de20b77ae2e522fe1a5c730b426a5b60ac86f5 (diff) | |
download | markdown-cd7324333a995eeb62a3e6eacdb3b179c6256133.tar.gz markdown-cd7324333a995eeb62a3e6eacdb3b179c6256133.tar.bz2 markdown-cd7324333a995eeb62a3e6eacdb3b179c6256133.zip |
Refactor Extension loading (#627)
Deprecated naming support is removed:
* Removed special treatment for modules in `markdown.extensions`
* Removed support for `mdx_` prefixes.
Support for Entry Point names added:
Support for "short names" are now implemented with entry points.
Therefore all the users who call extension names as `toc` will not
get errors as the builtin extensions all have entry points defined
which match the old "short names" for modules in
`markdown.extensions`. The benefit is that any extension can offer
the same support without requiring the user to manually copy a file
to that location on the file system (way to many extension authors
have included such instructions in their installation documentation).
The one odd thing about this is that we have been issuing a
DeprecationWarning for short names and now they are fully supported
again. But I think it's the right thing to do.
Support for using dot notation is not removed. After all, it was never
deprecated. And we shouldn't "force" entry points. There are plenty of
reasons why users may not want that and not all of them can be
resolved by using class instances instead.
All of the following ways to load an extension are valid:
# Class instance
from markdown.extensions.toc import TocExtension
markdown.markdown(src, extensions=[TocExtension()]
# Entry point name
markdown.markdown(src, extensions=['toc'])
# Dot notation with class
markdown.markdown(src, extensions=['markdown.extensions.toc:TocExtension'])
# Dot notation without class
markdown.markdown(src, extensions=['markdown.extensions.toc'])
Diffstat (limited to 'docs/cli.md')
-rw-r--r-- | docs/cli.md | 34 |
1 files changed, 19 insertions, 15 deletions
diff --git a/docs/cli.md b/docs/cli.md index dbac2c4..35c77b4 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -118,16 +118,26 @@ Using Extensions To load a Python-Markdown extension from the command line use the `-x` (or `--extension`) option. The extension module must be on your `PYTHONPATH` (see the [Extension API](extensions/api.md) for details). The extension can -then be invoked by the name of that module using Python's dot syntax: +then be invoked by the name assigned to an entry point or using Python's dot +notation to point to an extension + +For example, to load an extension with the assigned entry point name `myext`, +run the following command: + +```bash +python -m markdown -x myext input.txt +``` + +And to load an extension with Python's dot notation: ```bash -python -m markdown -x path.to.module input.txt +python -m markdown -x path.to.module:MyExtClass input.txt ``` To load multiple extensions, specify an `-x` option for each extension: ```bash -python -m markdown -x markdown.extensions.footnotes -x markdown.extensions.codehilite input.txt +python -m markdown -x myext -x path.to.module:MyExtClass input.txt ``` If the extension supports configuration options (see the documentation for the @@ -135,7 +145,7 @@ extension you are using to determine what settings it supports, if any), you can pass them in as well: ```bash -python -m markdown -x markdown.extensions.footnotes -c config.yml input.txt +python -m markdown -x myext -c config.yml input.txt ``` The `-c` (or `--extension_configs`) option accepts a file name. The file must be @@ -145,25 +155,19 @@ map to a Python Dictionary in the format required by the the file `config.yaml` referenced in the above example might look like this: ```yaml -markdown.extensions.footnotes: - PLACE_MARKER: ~~~~~~~~ - UNIQUE_IDS: True +myext: + option1: 'value1' + option2: True ``` Note that while the `--extension_configs` option does specify the -"markdown.extensions.footnotes" extension, you still need to load the extension -with the `-x` option, or the configuration for that extension will be ignored. +`myext` extension, you still need to load the extension with the `-x` option, +or the configuration for that extension will be ignored. The `--extension_configs` option will only support YAML configuration files if [PyYAML] is installed on your system. JSON should work with no additional dependencies. The format of your configuration file is automatically detected. -!!!warning - The previously documented method of appending the extension configuration - options as a string to the extension name will be deprecated in - Python-Markdown version 2.6. The `--extension_configs` option should be used - instead. See the [2.5 release notes] for more information. - [ec]: reference.html#extension_configs [YAML]: http://yaml.org/ [JSON]: http://json.org/ |