You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
114 lines
3.1 KiB
114 lines
3.1 KiB
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)']
|
|
... )
|