diff options
Diffstat (limited to 'docs/command_line.txt')
-rw-r--r-- | docs/command_line.txt | 98 |
1 files changed, 98 insertions, 0 deletions
diff --git a/docs/command_line.txt b/docs/command_line.txt new file mode 100644 index 0000000..d0134ea --- /dev/null +++ b/docs/command_line.txt @@ -0,0 +1,98 @@ +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 + |