rendering
This module holds helpers responsible for augmentations to the Markdown sub-documents produced by handlers.
HeadingShiftingTreeprocessor(md, shift_by)
¤
Bases: Treeprocessor
Shift levels of all Markdown headings according to the configured base level.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
md |
Markdown
|
A |
required |
shift_by |
int
|
The number of heading "levels" to add to every heading. |
required |
Source code in mkdocstrings/handlers/rendering.py
167 168 169 170 171 172 173 174 175 |
|
Highlighter(md)
¤
Bases: Highlight
Code highlighter that tries to match the Markdown configuration.
Picking up the global config and defaults works only if you use the codehilite
or
pymdownx.highlight
(recommended) Markdown extension.
-
If you use
pymdownx.highlight
, highlighting settings are picked up from it, and the default CSS class is.highlight
. This also means the default ofguess_lang: false
. -
Otherwise, if you use the
codehilite
extension, settings are picked up from it, and the default CSS class is.codehilite
. Also consider settingguess_lang: false
. -
If neither are added to
markdown_extensions
, highlighting is enabled anyway. This is for backwards compatibility. If you really want to disable highlighting even in mkdocstrings, add one of these extensions anyway and setuse_pygments: false
.
The underlying implementation is pymdownx.highlight
regardless.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
md |
Markdown
|
The Markdown instance to read configs from. |
required |
Source code in mkdocstrings/handlers/rendering.py
59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 |
|
highlight(src, language=None, *, inline=False, dedent=True, linenums=None, **kwargs)
¤
Highlight a code-snippet.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
src |
str
|
The code to highlight. |
required |
language |
Optional[str]
|
Explicitly tell what language to use for highlighting. |
None
|
inline |
bool
|
Whether to highlight as inline. |
False
|
dedent |
bool
|
Whether to dedent the code before highlighting it or not. |
True
|
linenums |
Optional[bool]
|
Whether to add line numbers in the result. |
None
|
**kwargs |
Any
|
Pass on to |
{}
|
Returns:
Type | Description |
---|---|
str
|
The highlighted code as HTML text, marked safe (not escaped for HTML). |
Source code in mkdocstrings/handlers/rendering.py
76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 |
|
IdPrependingTreeprocessor(md, id_prefix)
¤
Bases: Treeprocessor
Prepend the configured prefix to IDs of all HTML elements.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
md |
Markdown
|
A |
required |
id_prefix |
str
|
The prefix to add to every ID. It is prepended without any separator. |
required |
Source code in mkdocstrings/handlers/rendering.py
126 127 128 129 130 131 132 133 134 |
|
MkdocstringsInnerExtension(headings)
¤
Bases: Extension
Extension that should always be added to Markdown sub-documents that handlers request (and only them).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
headings |
List[Element]
|
A list that will be populated with all HTML heading elements encountered in the document. |
required |
Source code in mkdocstrings/handlers/rendering.py
228 229 230 231 232 233 234 235 |
|
extendMarkdown(md)
¤
Register the extension.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
md |
Markdown
|
A |
required |
Source code in mkdocstrings/handlers/rendering.py
237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 |
|
ParagraphStrippingTreeprocessor
¤
Bases: Treeprocessor
Unwraps the
element around the whole output.