aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorWaylan Limberg <waylan.limberg@icloud.com>2016-06-06 11:47:22 -0400
committerWaylan Limberg <waylan.limberg@icloud.com>2016-06-06 11:47:22 -0400
commitf3f768770ea62ff567c229b342ca0dca79b9da3c (patch)
tree1e9c257997b75ed0b6b172b992ed0440c6de7c1e
parent4bf178ed08f3bec2cc37e16ee528d572fe1fb60b (diff)
downloadmarkdown-f3f768770ea62ff567c229b342ca0dca79b9da3c.tar.gz
markdown-f3f768770ea62ff567c229b342ca0dca79b9da3c.tar.bz2
markdown-f3f768770ea62ff567c229b342ca0dca79b9da3c.zip
Additional improvements to Codehilite docs. Addesses concerns raised in #480.
-rw-r--r--docs/extensions/code_hilite.txt63
1 files changed, 45 insertions, 18 deletions
diff --git a/docs/extensions/code_hilite.txt b/docs/extensions/code_hilite.txt
index 575ee48..d13b0e8 100644
--- a/docs/extensions/code_hilite.txt
+++ b/docs/extensions/code_hilite.txt
@@ -20,26 +20,53 @@ This extension is included in the standard Markdown library.
Setup
-----
-### Step 1: download and install Pygments ###
+### Step 1: Download and Install Pygments ###
You will also need to [download][dl] and install the Pygments package on your
-`PYTHONPATH`. The CodeHilite extension will produce HTML output without Pygments,
-but it won't highlight anything.
+`PYTHONPATH`. The CodeHilite extension will produce HTML output without
+Pygments, but it won't highlight anything (same behavior as setting
+`use_pygments` to `False`).
[dl]: http://pygments.org/download/
-### Step 2: add CSS classes ###
+### Step 2: Add CSS Classes ###
-You will need to determine the appropriate CSS classes and/or JavaScript with
-appropriate rules. The CSS classes either need to be defined in or linked from
-the header of your HTML templates. Ready-made [CSS files for Python][rich] are available.
+You will need to define the appropriate CSS classes with appropriate rules.
+The CSS rules either need to be defined in or linked from the header of your
+HTML templates. Pygments can generate CSS rules for you. Just run the following
+command from the command line:
-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 not be highlighted.
+ pygmentize -S default -f html -a codehilite > styles.css
+If you are using a different `css_class` (default: `codehilite`), then
+set the value of the `-a` option to that class name. The CSS rules will be
+written to the `styles.css` file which you can copy to your site and link from
+your HTML templates.
+
+If you would like to use a differant theme, swap out `default` for the desired
+theme. For a list of themes installed on your system (additional themes can be
+isntalled via Pygments plugins), run the following command:
+
+ pygmetize -L style
+
+!!! see also
+
+ GitHub user [richeland] has provided a number of different [CSS style
+ sheets][rich] which work with Pygments along with a [preview] of each theme.
+ The `css_class` used is the same as the default value for that option
+ (`codehilite`). However, the Python-Markdown project makes no guarantee that
+ richeland's CSS styles will work with the version of Pygments you are using.
+ To ensure complete compatibility, you should generate the CSS rules from
+ your own installation of Pygments.
+
+See Pygment's excellent [documentation] for more details. If no language is
+defined, Pygments will attempt to guess the language. When that fails, the code
+block will not be highlighted.
+
+[richeland]: https://github.com/richleland
[rich]: https://github.com/richleland/pygments-css
-[documentation]: http://pygments.org/docs
+[previews]: http://richleland.github.io/pygments-css/
+[documentation]: http://pygments.org/docs/
Syntax
@@ -98,8 +125,8 @@ Will result in:
# Code goes here ...
-Certain lines can be selected for emphasis with the colon syntax. When
-using Pygments' default CSS styles, emphasized lines have a yellow background.
+Certain lines can be selected for emphasis with the colon syntax. When
+using Pygments' default CSS styles, emphasized lines have a yellow background.
This is useful to direct the reader's attention to specific lines.
:::python hl_lines="1 3"
@@ -114,7 +141,7 @@ This is useful to direct the reader's attention to specific lines.
CodeHilite is completely backwards compatible so that if a code block is
encountered that does not define a language, the block is simply wrapped in
-`<pre>` tags and output.
+`<pre>` tags and output.
# Code goes here ...
@@ -128,15 +155,15 @@ Lets see the source for that:
</code></pre></div>
!!! Note
- When no language is defined, the Pygments highlighting engine will try to guess
- the language (unless `guess_lang` is set to `False`). Upon failure, the same
+ When no language is defined, the Pygments highlighting engine will try to guess
+ the language (unless `guess_lang` is set to `False`). Upon failure, the same
behavior will happen as described above.
Usage
-----
-See [Extensions](index.html) for general extension usage, specify `markdown.extensions.codehilite`
-as the name of the extension.
+See [Extensions](index.html) for general extension usage, specify
+`markdown.extensions.codehilite` as the name of the extension.
See the [Library Reference](../reference.html#extensions) for information about
configuring extensions.