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.

Setup

Generally, you may simply call the python markdown.py file from the command line. However, if you have fully installed Markdown (setup.py install or easy_install), then the markdown.py script will have been copied to you Python "Scripts" directory. Different systems require different methods to ensure that any files in the Python "Scripts" directory are on your system path.

• Windows:

  1. Assuming a default install on Windows, your "Scripts" directory is mostly likely something like C:\\Python25\Scripts. Verify the location of your "Scripts" directory and add it to you system path.

  2. Make sure Windows is setup to recognize files that end with the ".py" extension are associated with python.exe so that you can simply call the script directly.

  Note that due to a peculiarity of how things work on Windows, you cannot just cd into the directory of the source distribution and run markdown.py from there. It will try to import itself rather than the markdown library. While a safeguard has been put in place to block this from happening, if markdown.py is in the same directory as the markdown library, then the safeguard blocks both from importing and the script won't be able to run.

• Linux:

  As each Linux distribution is different and we can't possibly document all of them here, we'll provide a few helpful pointers:

  • Some systems will automatically install the script on your path. Try it and see if it works. Just run markdown.py from the command line.

  • Other systems may maintain a separate "Scripts" directory which you need to add to your path. Find it (check with your distribution) and either add it to your path or make a symbolic link to it from your path.

  • If you are sure markdown.py is on your path, but it still isn't being found, check the permissions of the file and make sure it is executable.

  As an alternative, you could just cd into the directory which contains the source distribution, and run it from there. However, remember that your markdown text files will not likely be in that directory, so it is much more convenient to have markdown.py on your path.

The Basics

To use markdown.py from the command line, run it as

$ markdown.py input_file.txt

or

$ markdown.py input_file.txt > output_file.html

More Options

If you are using Python 2.3 or higher, you can also use advanced command line options to specify encoding or to run extensions.

$ markdown.py --help
Usage: markdown.py INPUTFILE [options]

Options:
  -h, --help            show this help message and exit
  -f OUTPUT_FILE, --file=OUTPUT_FILE
                        write output to OUTPUT_FILE
  -e ENCODING, --encoding=ENCODING
                        encoding for input and output files
  -q, --quiet           suppress all messages
  -v, --verbose         print info messages
  -s SAFE_MODE, --safe=SAFE_MODE
                        safe mode ('replace', 'remove' or 'escape'  user's
                        HTML tag)
  -o OUTPUT_FORMAT, --output_format=OUTPUT_FORMAT
                        Format of output. One of 'xhtml1' (default) or
                        'html4'.
  --noisy               print debug messages
  -x EXTENSION, --extension=EXTENSION
                        load extension EXTENSION

Using Extensions

For an extension to be ran this way it must be provided in a module which should be in your python path (see Writing_Extensions for details). It can then be invoked by the name of that module:

$ markdown.py -x footnotes text_with_footnotes.txt > output.html

If the extension supports config options, you can pass them in as well:

$ markdown.py -x "footnotes(PLACE_MARKER=~~~~~~~~)" input.txt