Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,9 @@ nav:
- Getting started: index.md
- API Reference: api.md

hooks:
- mkdocs_pygments_hook.py

plugins:
- search
- mkdocstrings:
Expand Down
36 changes: 36 additions & 0 deletions mkdocs_pygments_hook.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# Copyright 2025 MOSTLY AI
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""MkDocs hook: Pygments 2.20+ HtmlFormatter expects filename to be a string.

pymdown-extensions can pass filename=None when highlighting block code with no
title (e.g. mkdocstrings signatures), which breaks html.escape().
"""


def on_config(config, **kwargs):
import pymdownx.highlight as ph

if not getattr(ph, "pygments", False):
return config

_orig = ph.BlockHtmlFormatter.__init__

def __init__(self, **options):
if options.get("filename") is None:
options = {**options, "filename": ""}
_orig(self, **options)

ph.BlockHtmlFormatter.__init__ = __init__ # type: ignore[method-assign]
return config
4 changes: 2 additions & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ gpu = [

[dependency-groups]
dev = [
"pytest>=8.0",
"pytest>=9.0.3",
"pytest-rerunfailures>=15.0",
"ruff>=0.11", # sync'ed with .pre-commit-config
"pre-commit>=4.0",
Expand All @@ -69,7 +69,7 @@ docs = [
"griffe>=1.0",
"pymdown-extensions>=10.0",
"griffe-fieldz>=0.2",
"black>=25.0",
"black>=26.3.1",
]

[project.urls]
Expand Down
Loading