Navigation
A black wall label marks the chapter you are in; a tomato point marks the page.
Stable Class names and props are not expected to change before 1.0.
In this chapter 15 pages
Top bar
The top bar of this site is the component: wordmark at left, chapter tabs, tools at right, a 3px rule underneath. Where the tabs do not fit, they first set closer and the inline search field narrows; where they still do not fit, they fold into a Menu button, and the field becomes an icon button that opens a native <details> panel. js/topbar.js measures the fit, so a site with three chapters keeps its tabs on a phone and one with nine folds them on a small laptop. Without the script the tabs fold below 72rem, and the menu still works.
The script also closes the menu when it should get out of the way: Esc closes it and puts focus back on its button, and a press outside it, or focus moving on past it, closes it too.
The theme toggle flips light and dark and keeps the choice in localStorage under ply-theme ("light" or "dark", no identifier), so the next page opens in it. Say so in a privacy notice. <ThemeToggle persist={false} /> keeps the choice for the page only and clears a stored one; in plain HTML, add data-ply-persist="false" to the toggle.
<TopBar brand="John Doe" brandHref="/" links={[
{ label: "Research", href: "/research/", current: true },
{ label: "Teaching", href: "/teaching/" },
]}>
<ThemeToggle />
</TopBar>| Prop | Effect | Default |
|---|---|---|
brand | Wordmark text | Polytope |
brandHref | Wordmark link | / |
links | Chapters: { label, href, current } | |
default slot | Tools on the right: Search, the theme toggle |
Search
Search reads the site's own Pagefind index, a static search that needs no server. It comes in two variants. The inline field in this site's top bar is the one to use in a top bar. The dialog is a button that opens a panel over the page.
Build the index after the site build, and mark what it should read: the main content of each page, and the kind of each page, which the panel shows over each group of results. Navigation, footers, and forms are left out on their own.
npx astro build && npx pagefind --site dist<main data-pagefind-body>
<article data-pagefind-meta="kind:Publications">...</article>
</main>Inline field
A compact field sits in the bar between the tabs and the tools, about 14 characters wide with a / key hint, and grows a little while it has focus. Results drop in a black panel under it: up to eight pages, grouped by kind, each with its title and one line of excerpt with the match marked in mustard. The panel ends with an "All results" link when you give it a results page. Before the reader types, the panel shows the hint and the quick links. When nothing matches, the panel says so and the links come back under a line of your choosing.
The field is a combobox. The arrow keys move through the results, Enter follows the chosen one, or opens the page set in resultsHref for the query when none is chosen, and Esc closes the panel and leaves the field. When nothing matches, the panel says so above the links. The result count is read out through a status region. / and Ctrl+K (Cmd+K on a Mac) focus the field from anywhere on the page, except while the reader types in another field. The Pagefind files load on the first focus, with a loading line in the panel. If they cannot load, the panel links to the page set in href.
js/topbar.js counts the field when it measures the tabs: the field's width comes out of the room the tabs have, so it never pushes a tab off the bar. When the tabs fold into the menu, the field becomes an icon button. Pressing it opens the field across the whole bar, over the wordmark and the tools, with a close button. Esc or the button puts the bar back, and the bar keeps its height throughout. Without JavaScript the field is hidden and the bar shows the plain link, as it does for the dialog.
<TopBar brand="John Doe" brandHref="/" links={links}>
<Search variant="inline" href="/search/" resultsHref="/search/"
placeholder="Search papers, talks, and notes"
hint="Finds papers, talks, and notes."
links={[{ label: "Publications", href: "/publications/" }, { label: "Teaching", href: "/teaching/" }]} />
<ThemeToggle />
</TopBar>Dialog
The dialog variant is the default. A button in the bar opens a panel over the page, with the page dimmed behind it. Press / or Ctrl+K (Cmd+K on a Mac) to open it, the arrow keys to move through results, Enter to follow one, and Esc to close it. Results show their matching sections too. Without JavaScript the button is a plain link to a page you choose.
<TopBar brand="John Doe" brandHref="/" links={links}>
<Search href="/publications/" placeholder="Search papers, talks, and notes"
links={[{ label: "Publications", href: "/publications/" }, { label: "Teaching", href: "/teaching/" }]} />
<ThemeToggle />
</TopBar>Props
| Prop | Effect | Default |
|---|---|---|
variant | "dialog" opens a panel over the page. "inline" is a field in the bar with a drop panel. | dialog |
href | Where the button goes without JavaScript, and the link shown if the index cannot load | # |
label, placeholder | The button's text and the field's placeholder | Search |
bundle | Folder of the Pagefind files, with the site's base path | /pagefind/ |
baseUrl | Prefix for result links when the site lives under a base path | / |
hint, links | A line and quick links shown before the reader types. The links also show when nothing matches. | |
resultsHref | Inline only. The site's results page. The panel's last row links to it with ?q= and the query added. Without it the row is left out. | |
emptyText | Inline only. The line above the links when nothing matches | Try one of these topics. |
ranking | Pagefind ranking options, such as { pageLength: 0.2 } so short records do not crowd out pages |
Events
The component sends three events from its <ply-search> element, which bubble, so a site can pass them on to its own analytics. None of them carries the query text. What a reader searches for is theirs, so the component neither sends nor exposes it. A site that wants a count of searches gets one without a privacy question.
| Event | Detail |
|---|---|
ply-search:open | The reader focused the field or opened the dialog. No detail. |
ply-search:results | { bucket: "0" | "1-5" | "6+" }, sent once when a query has settled, after the reader pauses typing. Never one per keystroke. |
ply-search:select | { url, kind }: the path and hash of the page followed, and its kind (empty when it has none, "all" for the All results link). |
document.addEventListener("ply-search:results", (e) => track("search", { bucket: e.detail.bucket }));
document.addEventListener("ply-search:select", (e) => track("search-select", e.detail));A record can carry meta.summary, which the panel shows in place of an excerpt. These docs add every token, class, and component that way, from a short script that uses Pagefind's Node API after the build.
Chapter tabs
<nav class="ply-cluster" style="--ply-cluster-gap: 0.25rem" aria-label="Example chapters">
<a class="ply-tab" href="#" aria-current="page">Research</a>
<a class="ply-tab" href="#">Teaching</a>
<a class="ply-tab" href="#">Notes</a>
<a class="ply-tab" href="#">CV</a>
</nav>Mark the current tab with aria-current="page"; the black label comes from that attribute, so the visual state and the announced state cannot disagree.
Sidebar
<nav class="ply-sidenav" aria-label="Example sections">
<p class="ply-sidenav__heading">Foundations</p>
<ul>
<li><a href="#">Color</a></li>
<li><a href="#" aria-current="page">Typography</a>
<div class="ply-toc">
<ul aria-label="On this page">
<li><a href="#" aria-current="true">Typefaces</a></li>
<li><a href="#">Scale</a></li>
</ul>
</div>
</li>
<li><a href="#">Motion</a></li>
</ul>
</nav>The page's own sections hang under the current page, on a hairline. With Astro, put them in the current slot, and the auto list fills itself:
<SideNav groups={groups}>
<div slot="current" class="ply-toc" data-auto><ul aria-label="On this page"></ul></div>
</SideNav>On this page
The list under the current page in this page's sidebar, and in the rail at the left of an article. Give it data-auto and an empty <ul>, put data-toc-scope on the article, and the script fills it from the h2 and h3 headings and follows your scroll. With Astro and Markdown headings, <Toc headings={headings} /> renders it on the server instead.
Breadcrumb
<ol class="ply-breadcrumb">
<li><a href="#">Research</a></li>
<li><a href="#">2026</a></li>
<li aria-current="page">Higher-order message passing</li>
</ol>Pager
<nav class="ply-pager" aria-label="Pages" style="margin-top:0">
<a href="#" rel="prev"><span>Previous</span><strong>Typography</strong></a>
<a class="ply-pager__next" href="#" rel="next"><span>Next</span><strong>Motion</strong></a>
</nav>A label with a subtitle, such as a paper's "Name: what it does", shows the name and keeps the rest for screen readers, so a long title does not outweigh the page; split={false} shows it whole. The labels balance across their lines. Where "Previous" and "Next" are not the right words, as on a list newest first, rename them.
<Pager label="More publications" prev={{ label: newer.title, href: newer.href }} next={{ label: older.title, href: older.href }}
prevText="Newer" nextText="Older" />On an article page, Article's foot slot sets the pager at the text's edge: <Pager slot="foot" ... />.
Section heads
A section's heading takes a way onward on the same line, such as "All publications". On a page of many sections, two marks make each section its own. rule opens it on a 3px rule that leads with a short tomato segment and climbs in three pixel steps at its end, which is the one retro move the kit makes. mark sets a small static complex before the title, seeded from a name, so each section draws its own and none of them moves. The rule goes inside the content width, and the full-width rule under a mast stays plain.
Publications
Projects
All projects<SectionHead title="Publications" rule mark="Publications" more={{ label: "All publications", href: "/publications/" }} />
<SectionHead title="Projects" more={{ label: "All projects", href: "/projects/", attrs: { "data-track": "see-all" } }} />The rule is also a class pair for markup of your own: .ply-rule--stair adds the steps and .ply-rule--lead the tomato segment, on an hr.ply-rule. The rule keeps its 3px in layout, since the steps rise into the space above it. The link is 24px tall at rest and 44px under a finger, and its arrow moves a little on hover.
Dated list
A short list of the latest entries under a wall label: a month and year over a kind in one column, then a linked title and the rest of the line. It suits news, talks, or releases, in a mast's side column or under a section heading. rest is plain text, and html passes it through as trusted markup.
- Sheaves in the lab. At Example Workshop.
- Higher-order message passing. Accepted at Example Venue.
- Example Prize. Best student paper.
<DatedList label="Latest" items={[
{ when: "Sep 2026", kind: "Talk", title: "Sheaves in the lab", href: "/talks/x/", rest: "At Example Workshop." },
]} />To close a mast's side column on the line where the exhibit's caption does, put the list in the mast's after slot and give the mast side. See Space and layout.
Site footer
A 3px rule, then who the site is at the start, the links in groups by meaning, and a hairline-topped colophon. The groups share one row when they fit. When they do not, they stack and right-align on one edge, so no row holds a lone link. Links are 24px tall at rest and 44px under a finger. The footer at the foot of this page is the same component.
<SiteFooter name="John Doe" lede="PhD student, Example University, Boston." top="Back to top" linksLabel="Elsewhere">
<Fragment slot="links">
<ul class="ply-site-footer__links ply-small" role="list">
<li><a class="ply-target" href="https://github.com/...">GitHub</a></li>
</ul>
<ul class="ply-site-footer__links ply-small" role="list">
<li><a class="ply-target" href="/privacy/">Privacy</a></li>
</ul>
</Fragment>
<Fragment slot="colophon">© 2026 John Doe.</Fragment>
</SiteFooter>The who slot replaces the name and the line under it. top adds a "Back to top" link to the end of the colophon, for a phone and for a visitor without script. A fine pointer at 48rem and wider does not see it. Group links inside .ply-site-footer__links, and put ply-target on each link so a finger gets 44px.
Back to top
BackToTop is a 44px button at the bottom right of a phone's screen, inside the safe area. It shows while the reader scrolls up from more than a screen down, and goes again on scrolling down, after 2.5 seconds, and when the end of the page's content is within a screen, so it never covers the last line or the footer's link. Hidden, it takes no touch and no tab stop. A click scrolls up, smoothly unless reduced motion is on, and moves focus to main. The button at the corner of this page on a phone is this component.
<main id="main">...</main>
<BackToTop />
<SiteFooter top="Back to top" ... />Put it once in the body, after main. js/backtop.js drives it and is part of js/all.js. In plain HTML, write <button class="ply-backtop" type="button" aria-label="Back to top" tabindex="-1" inert data-ply-backtop-button> with an arrow icon inside.