| 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 |
| |