Common issues and fixes
A running list of the problems that come up most often and the diagnostic steps that resolve them. Check here before opening a bug report.
npm install fails
The most common cause is an outdated Node.js runtime. Confirm with:
node --version
If the output is earlier than 18, upgrade. On macOS and Linux, nvm is a common version manager; on Windows, fnm works cross-platform.
Pagefind search returns nothing
Pagefind runs at the end of a production build, not during the live preview. When you use npm start (which starts the dev server), the Pagefind index is not regenerated. Run:
npm run build
Then confirm _site/pagefind/ exists and contains both pagefind.js and several .pf_fragment files.
Dark mode flashes a light theme on load
The theme-detection script must execute before the stylesheet loads; otherwise the browser renders the default theme briefly before switching. Confirm that {% include "partials/theme-init.inline.njk" %} appears inside the <head> of base.njk, before the <link rel="stylesheet"> tag.
Buttondown signup does nothing
Two things to check in order:
- Config: Open
src/_data/site.jsonand confirm thebuttondown.usernamefield matches your Buttondown account username exactly (case-sensitive). - Form action: View the signup form's page source. The
actionattribute should readhttps://buttondown.email/api/emails/embed-subscribe/YOUR-USERNAME.
CSS changes don't appear
Your browser is almost certainly serving a cached stylesheet. Force a reload with Cmd+Shift+R (macOS) or Ctrl+Shift+R (Windows/Linux). Project Broadsheet appends a ?v= cache-busting query to the stylesheet link, derived from the version in meta.js, bumping the version forces every visitor to pull the new file.
An article does not appear in its section or on the homepage
Verify the front matter:
title,date, andsectionare all required.datemust be a valid ISO date (e.g.2026-04-17).- The file extension must be
.md..markdownis not recognized. - The containing folder's name must match the
sectionvalue.
Still stuck?
- Browse GitHub Discussions to see whether someone else has reported the same issue.
- Report a bug if the issue looks new.
- Book a call if you would like one-on-one help.
Browse Support for community channels and paid support options, or book a call if you'd like me to set it up for you.