Skip to content

refactor: update pagefind and improve interface #4891

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
miketheman wants to merge 2 commits into
base: main
Choose a base branch
from
Open

refactor: update pagefind and improve interface #4891

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cde0b83
chore(deps): bump pagefind
miketheman Apr 4, 2026
cc2016a
refactor: replace pagefind-ui with new component
miketheman Apr 4, 2026
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
189 changes: 13 additions & 176 deletions pep_sphinx_extensions/pep_theme/static/style.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,19 @@
--colour-caution: var(--light, #ffa) var(--dark, #550);
--colour-attention: var(--light, #bdf) var(--dark, #045);
--colour-tip: var(--light, #bfc) var(--dark, #041);

/* Pagefind component UI — theme variable overrides */
--pf-text: var(--colour-text);
--pf-text-muted: var(--colour-rule-strong);
--pf-background: var(--colour-background);
--pf-border: var(--colour-background-accent-strong);
--pf-border-focus: var(--colour-links);
--pf-hover: var(--colour-background-accent-light);
--pf-mark: var(--colour-text-strong);
--pf-outline-width: 0px;
--pf-input-height: 30px;
--pf-border-radius: 3px;
--pf-searchbox-max-width: 100%;
}

img.invert-in-dark-mode {
Expand Down Expand Up @@ -420,182 +433,6 @@ dl.footnote > dd {
padding-bottom: 2rem;
font-weight: bold;
}
/* Pagefind search styling (custom, no default CSS) */
.pagefind-ui {
--pagefind-ui-primary: var(--colour-links);
--pagefind-ui-text: var(--colour-text);
--pagefind-ui-background: var(--colour-background);
--pagefind-ui-border: var(--colour-background-accent-strong);
font-family: inherit;
width: 100%;
}

/* Search form */
.pagefind-ui__form {
position: relative;
}

/* Search icon */
.pagefind-ui__form::before {
background-color: var(--pagefind-ui-text);
width: 14px;
height: 14px;
top: 8px;
left: 8px;
content: "";
position: absolute;
display: block;
opacity: 0.5;
-webkit-mask-image: url("data:image/svg+xml,%3Csvg width='18' height='18' viewBox='0 0 18 18' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12.7549 11.255H11.9649L11.6849 10.985C12.6649 9.845 13.2549 8.365 13.2549 6.755C13.2549 3.165 10.3449 0.255005 6.75488 0.255005C3.16488 0.255005 0.254883 3.165 0.254883 6.755C0.254883 10.345 3.16488 13.255 6.75488 13.255C8.36488 13.255 9.84488 12.665 10.9849 11.685L11.2549 11.965V12.755L16.2549 17.745L17.7449 16.255L12.7549 11.255ZM6.75488 11.255C4.26488 11.255 2.25488 9.245 2.25488 6.755C2.25488 4.26501 4.26488 2.255 6.75488 2.255C9.24488 2.255 11.2549 4.26501 11.2549 6.755C11.2549 9.245 9.24488 11.255 6.75488 11.255Z' fill='%23000000'/%3E%3C/svg%3E%0A");
mask-image: url("data:image/svg+xml,%3Csvg width='18' height='18' viewBox='0 0 18 18' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12.7549 11.255H11.9649L11.6849 10.985C12.6649 9.845 13.2549 8.365 13.2549 6.755C13.2549 3.165 10.3449 0.255005 6.75488 0.255005C3.16488 0.255005 0.254883 3.165 0.254883 6.755C0.254883 10.345 3.16488 13.255 6.75488 13.255C8.36488 13.255 9.84488 12.665 10.9849 11.685L11.2549 11.965V12.755L16.2549 17.745L17.7449 16.255L12.7549 11.255ZM6.75488 11.255C4.26488 11.255 2.25488 9.245 2.25488 6.755C2.25488 4.26501 4.26488 2.255 6.75488 2.255C9.24488 2.255 11.2549 4.26501 11.2549 6.755C11.2549 9.245 9.24488 11.255 6.75488 11.255Z' fill='%23000000'/%3E%3C/svg%3E%0A");
-webkit-mask-size: 100%;
mask-size: 100%;
z-index: 9;
pointer-events: none;
}

/* Search input */
.pagefind-ui__search-input {
height: 30px;
padding: 4px 28px 4px 28px;
background-color: var(--pagefind-ui-background);
border: 1px solid var(--pagefind-ui-border);
border-radius: 3px;
font-size: 0.875rem;
font-family: inherit;
appearance: none;
-webkit-appearance: none;
width: 100%;
box-sizing: border-box;
color: var(--pagefind-ui-text);
}
.pagefind-ui__search-input:focus {
outline: none;
border-color: var(--pagefind-ui-primary);
}
.pagefind-ui__search-input::placeholder {
color: var(--pagefind-ui-text);
opacity: 0.5;
}

/* Clear button - fixed position relative to input (30px height, center button) */
.pagefind-ui__search-clear {
position: absolute;
top: 5px;
right: 4px;
padding: 2px 6px;
color: var(--pagefind-ui-text);
font-size: 0.75rem;
cursor: pointer;
background-color: var(--pagefind-ui-background);
border: none;
opacity: 0.6;
}
.pagefind-ui__search-clear:hover {
opacity: 1;
}

/* Results container */
.pagefind-ui__results-area {
margin-top: 0.5rem;
}

/* Results list */
#pep-sidebar .pagefind-ui__results {
list-style: none;
padding: 0;
margin: 0;
}

/* Individual result */
.pagefind-ui__result {
padding: 0.5rem 0 0.5rem 0.5rem;
border-bottom: 1px solid var(--colour-rule-light);
}
.pagefind-ui__result:last-child {
border-bottom: none;
}

/* Result link */
.pagefind-ui__result-link {
font-weight: bold;
font-size: 0.9rem;
text-decoration: none;
color: var(--colour-links);
}
.pagefind-ui__result-link:hover {
text-decoration: underline;
}

/* Result title */
.pagefind-ui__result-title {
margin: 0;
}

/* Result excerpt/snippet */
.pagefind-ui__result-excerpt {
font-size: 0.8rem;
color: var(--colour-text);
margin: 0.25rem 0 0;
line-height: 1.4;
}

/* Highlight matches in results */
.pagefind-ui__result-excerpt mark,
mark.pagefind-ui__highlight {
background-color: var(--colour-caution);
color: inherit;
padding: 0 2px;
}

/* Message when no results */
.pagefind-ui__message {
font-size: 0.85rem;
color: var(--colour-text);
padding: 0.5rem 0;
}

/* Loading state */
.pagefind-ui__loading {
font-size: 0.85rem;
color: var(--colour-text);
opacity: 0.7;
}

/* Sub-results (nested) */
.pagefind-ui__result-nested {
margin-left: 1rem;
padding: 0.25rem 0;
}
.pagefind-ui__result-nested .pagefind-ui__result-link {
font-weight: normal;
font-size: 0.85rem;
}

/* Button styling */
.pagefind-ui__button {
background: var(--colour-background-accent-light);
border: 1px solid var(--colour-background-accent-strong);
padding: 0.4rem 0.8rem;
border-radius: 4px;
cursor: pointer;
font-size: 0.85rem;
color: var(--colour-text);
margin-top: 0.5rem;
}
.pagefind-ui__button:hover {
background: var(--colour-background-accent-medium);
}

/* Drawer (expandable results container) */
.pagefind-ui__drawer {
overflow: hidden;
}

/* Suppress unused pagefind elements */
.pagefind-ui__suppressed {
display: none;
}

.reference.external > strong {
font-weight: normal; /* Fix strong links for :pep: and :rfc: roles */
Expand Down
28 changes: 6 additions & 22 deletions pep_sphinx_extensions/pep_theme/templates/page.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
<title>{{ title + " | peps.python.org"|safe }}</title>
<link rel="shortcut icon" href="{{ pathto('_static/py.png', resource=True) }}">
<link rel="canonical" href="https://peps.python.org/{{ pagename }}/">
<link rel="stylesheet" href="/pagefind/pagefind-component-ui.css" type="text/css">
<link rel="stylesheet" href="{{ pathto('_static/style.css', resource=True) }}" type="text/css">
<link rel="stylesheet" href="{{ pathto('_static/mq.css', resource=True) }}" type="text/css">
<link rel="stylesheet" href="{{ pathto('_static/pygments.css', resource=True) }}" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light">
Expand Down Expand Up @@ -47,7 +48,9 @@ <h1 data-pagefind-ignore>Python Enhancement Proposals</h1>
</button>
</header>
{# Mobile search box - visible only on small screens #}
<div id="mobile-search" class="mobile-search-container"></div>
<div id="mobile-search" class="mobile-search-container">
<pagefind-searchbox hide-shortcut style="font-family: inherit"></pagefind-searchbox>
</div>
{# Exclude noisy non-PEP pages from Pagefind indexing #}
{%- if pagename.startswith(("404", "numerical", "pep-0000", "topic")) %}
<article>
Expand All @@ -60,7 +63,7 @@ <h1 data-pagefind-ignore>Python Enhancement Proposals</h1>
</article>
{%- if not pagename.startswith(("404", "numerical")) %}
<nav id="pep-sidebar">
<div id="search"></div>
<pagefind-searchbox shortcut="/" style="font-family: inherit"></pagefind-searchbox>
<h2>Contents</h2>
{{ toc }}
<br>
Expand All @@ -79,25 +82,6 @@ <h2>Contents</h2>
{%- endif %}
<script src="https://analytics.python.org/js/script.outbound-links.js"
data-domain="peps.python.org" defer></script>
<script src="/pagefind/pagefind-ui.js"></script>
<script>
window.addEventListener('DOMContentLoaded', (event) => {
// Ranking configuration to boost exact title matches
const searchOptions = {
ranking: {
termSimilarity: 9.0, // Higher values favor exact matches
termFrequency: 0.5, // Lower values reduce penalty for low term frequency
pageLength: 0.2, // Lower values reduce the impact of page length
}
};

// Initialize pagefind for either mobile or desktop, not both
if (window.innerWidth <= 640) {
new PagefindUI({ element: "#mobile-search", ...searchOptions, showSubResults: false });
} else {
new PagefindUI({ element: "#search", ...searchOptions, showSubResults: true });
}
});
</script>
<script src="/pagefind/pagefind-component-ui.js" type="module"></script>
</body>
</html>
2 changes: 1 addition & 1 deletion requirements.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Sphinx >= 5.1.1, != 6.1.0, != 6.1.1, < 8.1.0
docutils >= 0.19.0
sphinx-notfound-page >= 1.0.2
# For search
pagefind[bin] >= 1.4.0
pagefind[bin] >= 1.5.0

# For tests
pytest>=9
Expand Down
Loading