aboutsummaryrefslogtreecommitdiffstats
path: root/docs/command_line.md
diff options
context:
space:
mode:
authorWaylan Limberg <waylan@gmail.com>2011-08-23 10:53:49 -0400
committerWaylan Limberg <waylan@gmail.com>2011-08-23 10:53:49 -0400
commita6fd7b5cba69cad049046b3a372d0f2d6c495abe (patch)
tree42a8987d08eb5a05eb2b3cb1399540583e8cbf67 /docs/command_line.md
parente5b2813bbf02710c7deb148896085a3dac4828dc (diff)
downloadmarkdown-a6fd7b5cba69cad049046b3a372d0f2d6c495abe.tar.gz
markdown-a6fd7b5cba69cad049046b3a372d0f2d6c495abe.tar.bz2
markdown-a6fd7b5cba69cad049046b3a372d0f2d6c495abe.zip
Renamed *.txt -> *.md in docs.
Diffstat (limited to 'docs/command_line.md')
-rw-r--r--docs/command_line.md101
1 files changed, 101 insertions, 0 deletions
diff --git a/docs/command_line.md b/docs/command_line.md
new file mode 100644
index 0000000..4ade8c1
--- /dev/null
+++ b/docs/command_line.md
@@ -0,0 +1,101 @@
+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 (``setup.py install`` or ``easy_install markdown``) to run the command
+line script.
+
+Assuming the `python` executable is on your system path, just run the following:
+
+ python -m markdown [options] [args]
+
+That will run the module as a script. Note that on older python versions (2.5
+and 2.6), you may need to specify the appropriate module:
+
+ python -m markdown.__main__ [options] [args]
+
+Use the `--help` option for available options:
+
+ python -m markdown --help
+
+If you are using Python 2.4 or you don't want to have to call the python
+executable directly, follow the instructions below:
+
+Setup
+-----
+
+Upon installation, the ``markdown_py`` script will have been copied to
+your 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 of Python on Windows, your "Scripts" directory
+ is most likely something like ``C:\\Python26\Scripts``. Verify the location
+ of your "Scripts" directory and add it to you system path.
+
+ Calling ``markdown_py`` from the command line will call the wrapper batch
+ file ``markdown_py.bat`` in the "Scripts" directory created during install.
+
+* __*nix__ (Linux, OSX, BSD, Unix, etc.):
+
+ As each *nix 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.
+
+__Note:__ Python-Markdown uses "markdown_py" as a script name because
+the Perl implementation has already taken the more obvious name "markdown".
+Additionally, the default Python configuration on some systems would cause a
+script named "markdown.py" to fail by importing itself rather than the markdown
+library. Therefore, the script has been named "markdown_py" as a compromise. If
+you prefer a different name for the script on your system, it is suggested that
+you create a symbolic link to `markdown_py` with your preferred name.
+
+Usage
+-----
+
+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
+
+For a complete list of options, run
+
+ $ markdown_py --help
+
+Using Extensions
+----------------
+
+For an extension to be run from the command line 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
+