Using Python-Markdown on the Command Line§

While Python-Markdown is primarily a python library, a command line script is included as well. While there are many other command line implementations of Markdown, you may not have them installed, or you may prefer to use Python-Markdown’s various extensions.

Generally, you will want to have the Markdown library fully installed on your system to run the command line script. See the Installation instructions for details.

Basic Usage§

Python-Markdown’s command line script takes advantage of Python’s -m flag. Therefore, assuming the python executable is on your system path, use the following format:

python -m markdown [options] [args]

That will run the module as a script with the options and arguments provided.

At its most basic usage, one would simply pass in a file name as the only argument:

python -m markdown input_file.txt

Use the --help option for a list of all available options and arguments:

$ python -m markdown --help
Usage: __main__.py [options] [INPUTFILE]
       (STDIN is assumed if no INPUTFILE is given)

A Python implementation of John Gruber's Markdown. https://python-
markdown.github.io/

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -f OUTPUT_FILE, --file=OUTPUT_FILE
                        Write output to OUTPUT_FILE. Defaults to STDOUT.
  -e ENCODING, --encoding=ENCODING
                        Encoding for input and output files.
  -o OUTPUT_FORMAT, --output_format=OUTPUT_FORMAT
                        Use output format 'xhtml' (default) or 'html'.
  -x EXTENSION, --extension=EXTENSION
                        Load extension EXTENSION.
  -c CONFIG_FILE, --extension_configs=CONFIG_FILE
                        Read extension configurations from CONFIG_FILE.
                        CONFIG_FILE must be of JSON or YAML format. YAML
                        format requires that a python YAML library be
                        installed. The parsed JSON or YAML must result in a
                        python dictionary which would be accepted by the
                        'extension_configs' keyword on the markdown.Markdown
                        class. The extensions must also be loaded with the
                        `--extension` option.
  -q, --quiet           Suppress all warnings.
  -v, --verbose         Print all warnings.
  --noisy               Print debug messages.

WARNING: The Python-Markdown library does NOT sanitize its HTML output. If you
are processing Markdown input from an untrusted source, it is your
responsibility to ensure that it is properly sanitized. For more information
see <https://python-markdown.github.io/sanitization/>.

Warning

The Python-Markdown library does not sanitize its HTML output. If you are processing Markdown input from an untrusted source, it is your responsibility to ensure that it is properly sanitized. For more information see Sanitizing HTML Output.

Piping Input and Output§

Piping input and output (on STDIN and STDOUT) is fully supported. For example:

Console

echo "Some **Markdown** text." | python -m markdown > output.html

output.html

<p>Some <strong>Markdown</strong> Text.</p>

As Python-Markdown only ever outputs HTML fragments (no <html>, <head>, and <body> tags), it is generally expected that the command line interface will always be used to pipe output to a templating engine. In the event that no additional content is needed and the output only needs to be wrapped in otherwise empty <html>, <head>, and <body> tags, JustHTML can do that with with a single command:

Console

echo "Some **Markdown** text." | python -m markdown | justhtml - --fragment > output.html

output.html

<html>
  <head></head>
  <body>
    <p>Some <strong>Markdown</strong> Text.</p>
  </body>
</html>

If you don’t need or want JustHTML’s HTML sanitation, you can disable it with the