From 2eb6b2d233593ee04b16c8b5000925a5850d0257 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Klinkovsk=C3=BD?= Date: Sat, 15 Feb 2014 18:57:47 +0100 Subject: docs: update codehilite documentation --- docs/extensions/code_hilite.txt | 139 +++++++++++++++++++++------------------- 1 file changed, 72 insertions(+), 67 deletions(-) (limited to 'docs') diff --git a/docs/extensions/code_hilite.txt b/docs/extensions/code_hilite.txt index 92f60f8..cbbac96 100644 --- a/docs/extensions/code_hilite.txt +++ b/docs/extensions/code_hilite.txt @@ -15,7 +15,7 @@ Python-Markdown code blocks using [Pygments][]. [Pygments]: http://pygments.org/ -This extension is included in the Markdown library. +This extension is included in the standard Markdown library. Setup ----- @@ -51,111 +51,116 @@ block contains and each one has a different result. [syntax]: http://daringfireball.net/projects/markdown/syntax#precode -* ###SheBang (with path) +### 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: +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: -* ###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. + #!/usr/bin/python + # Code goes here ... - #!python - # Code goes here ... +### SheBang (no path) ### - Will result in: +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 ... -* ###Colons +Will result in: - 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. + # Code goes here ... - :::python - # Code goes here ... +### Colons ### - Will result in: +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 ... - Certain lines can be selected for emphasis with the colon syntax. By - default, emphasized lines have a yellow background. This is useful to - direct the reader's attention. +Will result in: - :::python hl_lines="1 3" - # This line is emphasized - # This line isn't - # This line is emphasized + # Code goes here ... - (`hl_lines` is named for Pygments' "highlighted lines" option.) +Certain lines can be selected for emphasis with the colon syntax. By +default, emphasized lines have a yellow background. This is useful to +direct the reader's attention. -* ###When No Language is Defined + :::python hl_lines="1 3" + # This line is emphasized + # This line isn't + # This line is emphasized - CodeHilite is completely backward compatible so that if a code block is - encountered that does not define a language, the block is simply wrapped in - `
` tags and output. 
+!!! Note
+    `hl_lines` is named for Pygments' option meaning "highlighted lines".
 
-            # Code goes here ...
+### When No Language is Defined ###
 
-    Will result in:
+CodeHilite is completely backward compatible so that if a code block is
+encountered that does not define a language, the block is simply wrapped in
+`
` tags and output. 
 
         # Code goes here ...
 
-    Lets see the source for that:
+Will result in:
 
-        
# Code goes here ...
-        

+    # Code goes here ...
 
-    !!! 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 
-        behavior will happen as described above.
+Lets see the source for that:
+
+    
# Code goes here ...
+    

+
+!!! 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 
+    behavior will happen as described above.
 
 Usage
 -----
 
-From the Python interpreter:
+See [Extensions](./index.html) for general extension usage, specify `codehilite`
+as the name of the extension.
 
-    >>> html = markdown.markdown(text, extensions=['codehilite'])
+See the [Library Reference](../reference.html#extensions) for information about
+configuring extensions.
 
-To force every code block to have line numbers, even when using 
-colons (`:::`) for language identification, set `linenums` to `True`.
+The following options are provided to configure the output:
 
-    >>> html = markdown.markdown(text,
-    ...     extensions=['codehilite(linenums=True)']
-    ... )
+* **linenums**:
+    Use line numbers. Possible values are `True` for yes, `False` for no and
+    `None` for auto. Defaults to `None`.
 
-To turn off all line numbers, even when using SheBangs (`#!`) for 
-language identification, set `linenums` to `False`.
+    Using `True` will force every code block to have line numbers, even when
+    using colons (`:::`) for language identification.
 
-    >>> html = markdown.markdown(text,
-    ...     extensions=['codehilite(linenums=False)']
-    ... )
+    Using `False` will turn off all line numbers, even when using SheBangs
+    (`#!`) for language identification.
 
-To prevent Pygments from guessing the language (only highlighting
-blocks when you explicitly request it) set the `guess_lang` setting to `False`.
+* **guess_lang**:
+    Automatic language detection. Defaults to `True`.
 
-    >>> html = markdown.markdown(text,
-    ...     extensions=['codehilite(guess_lang=False)']
-    ... )
+    Using `False` will prevent Pygments from guessing the language, and thus
+    highlighting blocks only when you explicitly set the language.
 
-To assign a CSS class differant than the default ('codehilite') on the
-code's wrapping div, define a custom class with the `css_class` setting.
+* **css_class**:
+    Set CSS class name for the wrapper `
` tag. Defaults to
+    `codehilite`.
 
-    >>> html = markdown.markdown(text,
-    ...    extensions=['codehilite(css_class=myclass)']
-    ... )
+* **pygments_style**:
+    Pygments HTML Formatter Style (ColorScheme). Defaults to `default`.
+
+    !!! Note
+        This is useful only when `noclasses` is set to `True`, otherwise the
+        CSS style shall be provided by the end user.
 
+* **noclasses**:
+    Use inline styles instead of CSS classes. Defaults to `False`.
-- 
cgit v1.2.3