Maintain Content and Search

Review page changes, preserve destinations, and verify Pagefind search against the built and deployed site.

Treat documentation changes as small releases: update the owning page, verify examples and links, build, and check deployment. Source files and Git history can support this workflow without a separate content editor.

Add or change a page

Create a page under src/content/docs/ with an explicit title and useful description. sidebar.order positions it among siblings; sidebar.label supplies a shorter navigation label.

---
title: Rotate an API Key
description: Create a replacement key, move clients, and revoke the old key.
sidebar:
  label: Rotate keys
  order: 30
---

## Before you start

Describe the required access and the effect on existing clients.

Review against the product version described. Include prerequisites, a working example, expected results, and failure cases. Update the canonical page when its reader task is unchanged; add a page for a distinct outcome.

The default sidebar discovers the content tree; a separate page-list entry is unnecessary. Use configuration and navigation for section labels and ordering.

Rename or retire a page

Moving a file can change its URL. Find incoming content and navigation links, update them to the new target, and configure a host redirect for bookmarks. Check fragment links when headings change.

Point obsolete procedures to replacements and identify applicable versions. Retain older content while customers need it. Check asset references from older releases before deletion.

sidebar.hidden: true affects navigation. It does not prevent direct requests, remove every search result, or establish reader authorization. Keep confidential material outside a public build.

Verify production search

Publier uses Pagefind for full-text search. The scaffold explicitly registers pagefind() in astro.config.ts; retain it. Publier supplies the dialog while the integration builds an index from emitted HTML.

corepack pnpm run build
corepack pnpm run preview

Open the preview, press Cmd/Ctrl+K, search for a distinctive changed phrase, and follow the result. Check its destination, title, and snippet. Repeat after deployment; a result in an old tab does not qualify the new artifact.

Symptom	Check
Dialog opens, results fail	Browser requests for `/pagefind/`; publish the generated directory with `dist/`
New page missing	Verify the built HTML contains it; rebuild and deploy HTML and index together
Old content remains	Deployed revision, host/browser cache, and service-worker cache if used
Navigation appears in snippets	Custom layouts and Pagefind’s body/ignore attributes
Domain-root preview works, subpath fails	Built-in search uses root `/pagefind/` URLs; see hosting limits

Exclude an element from Pagefind with:

<div data-pagefind-ignore>Repeated supplementary UI text</div>

This also excludes the subtree from Publier’s rendered Markdown exports; it does not restrict access to the HTML. Review Pagefind indexing controls when customizing layouts.

Review before publishing

Check direct URLs and client navigation, a narrow viewport, and both themes. Exercise touched code copy, links, downloads, image alternatives, and tab panels. A reviewer should be able to follow the procedure from its stated prerequisites.

Publish HTML, assets, search, sitemap, and enabled AI outputs from one build. Retain the qualified artifact and source revision for rollback.