aboutsummaryrefslogtreecommitdiffstats
path: root/docs/extensions/CodeHilite.txt
diff options
context:
space:
mode:
authorWaylan Limberg <waylan@gmail.com>2009-03-19 21:35:21 -0400
committerWaylan Limberg <waylan@gmail.com>2009-03-19 21:35:21 -0400
commitc1eb12e10480a60e2fc26a0091cafb779553a4fe (patch)
tree98b0a5cdceb23430c84433f25516796ec3e7ed06 /docs/extensions/CodeHilite.txt
parent70c81659eca814bb037b93c95996210d192e5ca5 (diff)
downloadmarkdown-c1eb12e10480a60e2fc26a0091cafb779553a4fe.tar.gz
markdown-c1eb12e10480a60e2fc26a0091cafb779553a4fe.tar.bz2
markdown-c1eb12e10480a60e2fc26a0091cafb779553a4fe.zip
Added documentation for the rest of the extensions included with the distribution.
Diffstat (limited to 'docs/extensions/CodeHilite.txt')
-rw-r--r--docs/extensions/CodeHilite.txt113
1 files changed, 113 insertions, 0 deletions
diff --git a/docs/extensions/CodeHilite.txt b/docs/extensions/CodeHilite.txt
new file mode 100644
index 0000000..482ad60
--- /dev/null
+++ b/docs/extensions/CodeHilite.txt
@@ -0,0 +1,113 @@
+CodeHilite
+==========
+
+Summary
+-------
+
+The CodeHilite Extension adds code/syntax highlighting to standard
+Python-Markdown code blocks using [Pygments][].
+
+[Python-Markdown]: http://www.freewisdom.org/projects/python-markdown/
+[Pygments]: http://pygments.org/
+
+This extension is included in the Markdown library.
+
+Setup
+-----
+
+You will also need to [download][dl] and install the Pygments package on your
+`PYTHONPATH`. You will need to determine the appropriate CSS classes and create
+appropriate rules for them, which are either defined in or linked from the
+header of your HTML templates. See the excellent [documentation][] for more
+details. If no language is defined, Pygments will attempt to guess the
+language. When that fails, the code block will display as un-highlighted code.
+
+[dl]: http://pygments.org/download/
+[documentation]: http://pygments.org/docs
+
+**Note:** The css and/or javascript is not included as part of this extension
+but shall always be provided by the end user.
+
+Syntax
+------
+
+The CodeHilite Extension follows the same [syntax][] as regular Markdown code
+blocks, with one exception. The hiliter needs to know what language to use for
+the code block. There are three ways to tell the hiliter what language the code
+block contains and each one has a different result.
+
+[syntax]: http://daringfireball.net/projects/markdown/syntax#precode
+
+###SheBang (with path)
+
+If the first line of the codeblock contains a shebang, the language is derived
+from that and line numbers are used.
+
+ #!/usr/bin/python
+ # Code goes here ...
+
+Will result in:
+
+ #!/usr/bin/python
+ # Code goes here ...
+
+
+###SheBang (no path)
+
+If the first line contains a shebang, but the shebang line does not contain a
+path (a single `/` or even a space), then that line is removed from the code
+block before processing. Line numbers are used.
+
+ #!python
+ # Code goes here ...
+
+Will result in:
+
+ # Code goes here ...
+
+####Colons
+
+If the first line begins with three or more colons, the text following the
+colons identifies the language. The first line is removed from the code block
+before processing and line numbers are not used.
+
+ :::python
+ # Code goes here ...
+
+Will result in:
+
+ # Code goes here ...
+
+###When No Language is Defined
+
+CodeHilite is completely backward compatible so that if a code block is
+encountered that does not define a language, the block is simple wrapped in
+`<pre>` tags and output. Note: one exception would be that the Pygments
+highlighting engine will try to guess the language. Upon failure, the same
+behavior will happen as described here.
+
+ # Code goes here ...
+
+Will result in:
+
+ # Code goes here ...
+
+Lets see the source for that:
+
+ <div class="codehilite" ><pre><code># Code goes here ...
+ </code></pre></div>
+
+Usage
+-----
+
+From the Python interpreter:
+
+ >>> html = markdown.markdown(text, ['codehilite'])
+
+If you want every code block to have line numbers, even when using colons
+(`:::`) for language identification, the setting `force_linenos` is available
+to do so.
+
+ >>> html = markdown.markdown(text,
+ ... ['codehilite(force_linenos=True)']
+ ... )