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 ¤
HeadingShiftingTreeprocessor(md: Markdown, shift_by: int)
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
179 180 181 182 183 184 185 186 187 |
|
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
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 |
|
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
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 116 117 118 119 120 121 122 123 124 125 126 127 |
|
IdPrependingTreeprocessor ¤
IdPrependingTreeprocessor(md: Markdown, id_prefix: str)
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
138 139 140 141 142 143 144 145 146 |
|
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
241 242 243 244 245 246 247 248 |
|
extendMarkdown ¤
extendMarkdown(md: Markdown) -> None
Register the extension.
Parameters:
-
md
(Markdown
) –A
markdown.Markdown
instance.
Source code in src/mkdocstrings/handlers/rendering.py
250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 |
|
ParagraphStrippingTreeprocessor ¤
Bases: Treeprocessor
Unwraps the
element around the whole output.