rendering ¤
This module holds helpers responsible for augmentations to the Markdown sub-documents produced by handlers.
Classes:
-
HeadingShiftingTreeprocessor
–Shift levels of all Markdown headings according to the configured base level.
-
Highlighter
–Code highlighter that tries to match the Markdown configuration.
-
IdPrependingTreeprocessor
–Prepend the configured prefix to IDs of all HTML elements.
-
MkdocstringsInnerExtension
–Extension that should always be added to Markdown sub-documents that handlers request (and only them).
-
ParagraphStrippingTreeprocessor
–Unwraps the
element around the whole output.
HeadingShiftingTreeprocessor ¤
Bases: Treeprocessor
Shift levels of all Markdown headings according to the configured base level.
Parameters:
-
md
¤Markdown
) –A
markdown.Markdown
instance. -
shift_by
¤int
) –The number of heading "levels" to add to every heading.
Attributes:
-
shift_by
(int
) –The number of heading "levels" to add to every heading.
<h2>
withshift_by = 3
becomes<h5>
.
Source code in src/mkdocstrings/handlers/rendering.py
198 199 200 201 202 203 204 205 206 |
|
Highlighter ¤
Highlighter(md: Markdown)
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:
-
md
¤Markdown
) –The Markdown instance to read configs from.
Methods:
-
highlight
–Highlight a code-snippet.
Source code in src/mkdocstrings/handlers/rendering.py
67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 |
|
highlight ¤
highlight(
src: str,
language: str | None = None,
*,
inline: bool = False,
dedent: bool = True,
linenums: bool | None = None,
**kwargs: Any
) -> str
Highlight a code-snippet.
Parameters:
-
src
¤str
) –The code to highlight.
-
language
¤str | None
, default:None
) –Explicitly tell what language to use for highlighting.
-
inline
¤bool
, default:False
) –Whether to highlight as inline.
-
dedent
¤bool
, default:True
) –Whether to dedent the code before highlighting it or not.
-
linenums
¤bool | None
, default:None
) –Whether to add line numbers in the result.
-
**kwargs
¤Any
, default:{}
) –Pass on to
pymdownx.highlight.Highlight.highlight
.
Returns:
-
str
–The highlighted code as HTML text, marked safe (not escaped for HTML).
Source code in src/mkdocstrings/handlers/rendering.py
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 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 |
|
IdPrependingTreeprocessor ¤
Bases: Treeprocessor
Prepend the configured prefix to IDs of all HTML elements.
Parameters:
-
md
¤Markdown
) –A
markdown.Markdown
instance. -
id_prefix
¤str
) –The prefix to add to every ID. It is prepended without any separator.
Attributes:
-
id_prefix
(str
) –The prefix to add to every ID. It is prepended without any separator; specify your own separator if needed.
Source code in src/mkdocstrings/handlers/rendering.py
141 142 143 144 145 146 147 148 149 |
|
MkdocstringsInnerExtension ¤
Bases: Extension
Extension that should always be added to Markdown sub-documents that handlers request (and only them).
Parameters:
-
headings
¤list[Element]
) –A list that will be populated with all HTML heading elements encountered in the document.
Methods:
-
extendMarkdown
–Register the extension.
Source code in src/mkdocstrings/handlers/rendering.py
261 262 263 264 265 266 267 268 |
|
extendMarkdown ¤
extendMarkdown(md: Markdown) -> None
Register the extension.
Parameters:
-
md
¤Markdown
) –A
markdown.Markdown
instance.
Source code in src/mkdocstrings/handlers/rendering.py
270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 |
|
ParagraphStrippingTreeprocessor ¤
Bases: Treeprocessor
Unwraps the
element around the whole output.