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.

Setup

-----

Generally, you may simply call the ``markdown`` file from the command 

line. However, if you have fully installed Markdown (``setup.py install`` or 

``easy_install``), then the ``markdown`` 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**:

    Assuming a default install on Windows, your "Scripts" directory is most

    likely something like ``C:\\Python25\Scripts``. Verify the location of

    your "Scripts" directory and add it to you system path.

    Calling ``markdown`` from th ecommand line will call the wrapper batch file

    ``markdown.bat`` in the "Scripts" directory created during install.

* **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`` 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`` 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`` on your path.

The Basics

----------

To use ``markdown`` from the command line, run it as 

    $ markdown input_file.txt

or 

    $ markdown 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 --help

    Usage: markdown 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 -x footnotes text_with_footnotes.txt > output.html

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

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