Debian Codegraph @

docs/extensions/code_hilite.md

raw
1 title: CodeHilite Extension
2
3 # CodeHilite
4
5 ## Summary
6
7 The CodeHilite extension adds code/syntax highlighting to standard
8 Python-Markdown code blocks using [Pygments][].
9
10 [Pygments]: http://pygments.org/
11
12 This extension is included in the standard Markdown library.
13
14 ## Setup
15
16 ### Step 1: Download and Install Pygments
17
18 You will also need to [download][dl] and install the Pygments package on your
19 `PYTHONPATH`. The CodeHilite extension will produce HTML output without
20 Pygments, but it won't highlight anything (same behavior as setting
21 `use_pygments` to `False`).
22
23 [dl]: http://pygments.org/download/
24
25 ### Step 2: Add CSS Classes
26
27 You will need to define the appropriate CSS classes with appropriate rules.
28 The CSS rules either need to be defined in or linked from the header of your
29 HTML templates. Pygments can generate CSS rules for you. Just run the following
30 command from the command line:
31
32 ```bash
33 pygmentize -S default -f html -a .codehilite > styles.css
34 ```
35
36 If you are using a different `css_class` (default: `.codehilite`), then
37 set the value of the `-a` option to that class name. The CSS rules will be
38 written to the `styles.css` file which you can copy to your site and link from
39 your HTML templates.
40
41 If you would like to use a different theme, swap out `default` for the desired
42 theme. For a list of themes installed on your system (additional themes can be
43 installed via Pygments plugins), run the following command:
44
45 ```bash
46 pygmentize -L style
47 ```
48
49 See Pygments' excellent [documentation] for more details. If no language is
50 defined, Pygments will attempt to guess the language. When that fails, the code
51 block will not be highlighted.
52
53 !!! seealso "See Also"
54
55 GitHub user [richeland] has provided a number of different [CSS style
56 sheets][rich] which work with Pygments along with a [preview] of each theme.
57 The `css_class` used is `.highlight`. Therefore, one would need to override the
58 [`css_class`](#css_class) option when using richeland's CSS styles. However, the
59 Python-Markdown project makes no guarantee that richeland's CSS styles will
60 work with the version of Pygments you are using. To ensure complete
61 compatibility, you should generate the CSS rules from your own installation
62 of Pygments.
63
64 [richeland]: https://github.com/richleland
65 [rich]: https://github.com/richleland/pygments-css
66 [preview]: https://richleland.github.io/pygments-css/
67 [documentation]: http://pygments.org/docs/
68
69 ## Syntax
70
71 The CodeHilite extension follows the same [syntax][] as regular Markdown code
72 blocks, with one exception. The highlighter needs to know what language to use for
73 the code block. There are three ways to tell the highlighter what language the
74 code block contains and each one has a different result.
75
76 !!! Note
77 The format of the language identifier only effects the display of line numbers
78 if `linenums` is set to `None` (the default). If set to `True` or `False`
79 (see [Usage](#usage) below) the format of the identifier has no effect on the
80 display of line numbers -- it only serves as a means to define the language
81 of the code block.
82
83 [syntax]: https://daringfireball.net/projects/markdown/syntax#precode
84
85 ### Shebang (with path)
86
87 If the first line of the code block contains a shebang, the language is derived
88 from that and line numbers are used.
89
90 ```md
91 #!/usr/bin/python
92 # Code goes here ...
93 ```
94
95 Will result in:
96
97 #!/usr/bin/python
98 # Code goes here ...
99
100 ### Shebang (no path)
101
102 If the first line contains a shebang, but the shebang line does not contain a
103 path (a single `/` or even a space), then that line is removed from the code
104 block before processing. Line numbers are used.
105
106 ```md
107 #!python
108 # Code goes here ...
109 ```
110
111 Will result in:
112
113 #!python
114 # Code goes here ...
115
116 ### Colons
117
118 If the first line begins with three or more colons, the text following the
119 colons identifies the language. The first line is removed from the code block
120 before processing and line numbers are not used.
121
122 ```md
123 :::python
124 # Code goes here ...
125 ```
126
127 Will result in:
128
129 :::python
130 # Code goes here ...
131
132 Certain lines can be selected for emphasis with the colon syntax. When
133 using Pygments' default CSS styles, emphasized lines have a yellow background.
134 This is useful to direct the reader's attention to specific lines.
135
136 ```md
137 :::python hl_lines="1 3"
138 # This line is emphasized
139 # This line isn't
140 # This line is emphasized
141 ```
142
143 Will result in:
144
145 :::python hl_lines="1 3"
146 # This line is emphasized
147 # This line isn't
148 # This line is emphasized
149
150 !!! Note
151 `hl_lines` is named for Pygments' option meaning "highlighted lines".
152
153 ### When No Language is Defined
154
155 CodeHilite is completely backwards compatible so that if a code block is
156 encountered that does not define a language, the block is simply wrapped in
157 `<pre>` tags and output.
158
159 ```md
160 # Code goes here ...
161 ```
162
163 Will result in:
164
165 # Code goes here ...
166
167 Lets see the source for that:
168
169 ```html
170 <div class="codehilite"><pre><code># Code goes here ...
171 </code></pre></div>
172 ```
173
174 !!! Note
175 When no language is defined, the Pygments highlighting engine will try to guess
176 the language (unless `guess_lang` is set to `False`). Upon failure, the same
177 behavior will happen as described above.
178
179 ## Usage
180
181 See [Extensions](index.md) for general extension usage. Use `codehilite` as the
182 name of the extension.
183
184 See the [Library Reference](../reference.md#extensions) for information about
185 configuring extensions.
186
187 The following options are provided to configure the output:
188
189 * **`linenums`**{ #linenums }:
190 An alias to Pygments' `linenos` formatter option. Possible values are `True` for yes, `False` for no and `None`
191 for auto. Defaults to `None`.
192
193 Using `True` will force every code block to have line numbers, even when
194 using colons (`:::`) for language identification.
195
196 Using `False` will turn off all line numbers, even when using shebangs
197 (`#!`) for language identification.
198
199 * **`guess_lang`**{ #guess_lang }:
200 Automatic language detection. Defaults to `True`.
201
202 Using `False` will prevent Pygments from guessing the language, and thus
203 highlighting blocks only when you explicitly set the language.
204
205 * **`css_class`**{ #css_class }:
206 An alias to Pygments `cssclass` formatter option. Set CSS class name for the wrapper `<div>` tag. Defaults to
207 `codehilite`.
208
209 * **`pygments_style`**{ #pygments_style }:
210 Pygments HTML Formatter Style (`ColorScheme`). Defaults to `default`.
211
212 !!! Note
213 This is useful only when `noclasses` is set to `True`, otherwise the
214 CSS styles must be provided by the end user.
215
216 * **`noclasses`**{ #noclasses }:
217 Use inline styles instead of CSS classes. Defaults to `False`.
218
219 * **`use_pygments`**{ #use_pygments }:
220 Specifies the use of Pygments in generating the output.
221
222 If `True` (the default) and Pygments is available, CodeHilite will use
223 Pygments to analyze and format the output. Additionally, if using Pygments
224 &gt;= 2.4, the output will be wrapped in `<code>` tags, whereas earlier
225 versions will not.
226
227 Otherwise, Pygments will not be used. If a language is defined for a code block, it will be assigned to the
228 `<code>` tag as a class in the manner suggested by the [HTML5 spec][spec] and may be used by a JavaScript library
229 in the browser to highlight the code block. See the [`lang_prefix`](#lang_prefix) option to customize the prefix.
230
231 * **`lang_prefix`**{ #lang_prefix }:
232 The prefix prepended to the language class assigned to the HTML `<code>` tag. Default: `language-`.
233
234 * **`pygments_formatter`**{ #pygments_formatter }:
235 This option can be used to change the Pygments formatter used for highlighting code blocks. By default, this
236 is set to the string `'html'`, which means it'll use the default `HtmlFormatter` provided by Pygments.
237
238 This can be set to a string representing any of the other default formatters, or set to a formatter class (or
239 any callable).
240
241 The code's language is always passed to the formatter as an extra option `lang_str`, with the value formatted as
242 `{lang_prefix}{lang}`. If the language is unspecified, the language guessed by Pygments will be used. While
243 this option has no effect to the Pygments's builtin formatters, a user can make use of the language in their custom
244 formatter. See an example below.
245
246 To see what formatters are available and how to subclass an existing formatter, please visit [Pygments
247 documentation on this topic][pygments formatters].
248
249 * Any other Pygments' options:
250
251 All other options are accepted and passed on to Pygments' lexer and formatter. Therefore,
252 valid options include any options which are accepted by the [html formatter] or
253 whichever [lexer] the code's language uses. Invalid options are ignored without error.
254
255 A trivial example:
256
257 ```python
258 markdown.markdown(some_text, extensions=['codehilite'])
259 ```
260
261 To keep the code block's language in the Pygments generated HTML output, one can provide a custom Pygments formatter
262 that takes the `lang_str` option. For example,
263
264 ```python
265 from pygments.formatters import HtmlFormatter
266 from markdown.extensions.codehilite import CodeHiliteExtension
267
268
269 class CustomHtmlFormatter(HtmlFormatter):
270 def __init__(self, lang_str='', **options):
271 super().__init__(**options)
272 # lang_str has the value {lang_prefix}{lang}
273 # specified by the CodeHilite's options
274 self.lang_str = lang_str
275
276 def _wrap_code(self, source):
277 yield 0, f'<code class="{self.lang_str}">'
278 yield from source
279 yield 0, '</code>'
280
281
282 some_text = '''\
283 :::python
284 print('hellow world')
285 '''
286
287 markdown.markdown(
288 some_text,
289 extensions=[CodeHiliteExtension(pygments_formatter=CustomHtmlFormatter)],
290 )
291 ```
292
293 The formatter above will output the following HTML structure for a code block:
294
295 ```html
296 <div class="codehilite">
297 <pre>
298 <code class="language-python">
299 ...
300 </code>
301 </pre>
302 </div>
303 ```
304
305 [html formatter]: https://pygments.org/docs/formatters/#HtmlFormatter
306 [lexer]: https://pygments.org/docs/lexers/
307 [spec]: https://www.w3.org/TR/html5/text-level-semantics.html#the-code-element
308 [pygments formatters]: https://pygments.org/docs/formatters/