The documentation site for Squad, built with Astro, Tailwind CSS, and Pagefind for search.

• Node.js 20+ (LTS)
• Run npm install from the docs/ directory

All commands are run from the docs/ directory, or from the repo root using the docs: prefix.

npm run dev

Starts a local dev server at http://localhost:4321/squad/ with hot module reloading. Changes to markdown content, layouts, and components are reflected immediately.

Note: Search does not work in dev mode. Pagefind indexes are only generated during build, so the search modal will not return results. Use build + preview to test search.

npm run build

Runs two steps:

1. astro build — Compiles all pages to static HTML in dist/
2. npx pagefind --site dist — Indexes the HTML output to generate the search index at dist/pagefind/

The output in dist/ is what gets deployed to GitHub Pages.

npm run preview

Serves the dist/ directory locally so you can verify the production build, including working search.

Search is powered by Pagefind, a static search library that indexes the built HTML.

• Dev mode: Search UI appears but returns no results (no index exists).
• Build + Preview: Search works fully. The build step generates the Pagefind index, and preview serves it.
• Only pages with data-pagefind-body are indexed. This attribute is set on the <article> element in DocsLayout.astro and the blog post template.

docs/
├── astro.config.mjs        # Astro configuration (site, base path, plugins)
├── package.json             # Docs-specific dependencies
├── src/
│   ├── components/          # Astro components (Header, Sidebar, Search, etc.)
│   ├── content/
│   │   ├── blog/            # Blog posts (markdown)
│   │   └── docs/            # Documentation articles (markdown)
│   │       ├── concepts/
│   │       ├── cookbook/
│   │       ├── features/
│   │       ├── get-started/
│   │       ├── guide/
│   │       ├── reference/
│   │       └── scenarios/
│   ├── layouts/             # Page layouts (BaseLayout, DocsLayout)
│   ├── navigation.ts        # Sidebar navigation structure
│   ├── pages/               # Astro page routes
│   ├── plugins/             # Remark plugins (link rewriting)
│   └── styles/              # Global CSS (Tailwind)
├── public/                  # Static assets (images)
└── dist/                    # Build output (gitignored)

1. Create a markdown file under src/content/docs/{section}/your-page.md
2. Add a sidebar entry in src/navigation.ts under the appropriate NAV_SECTIONS section
3. Run the docs build test to verify: npx vitest run test/docs-build.test.ts (from repo root)

Create a markdown file under src/content/blog/ with frontmatter:

---
title: "Your Post Title"
date: 2026-03-08
---

Post content here.

Blog posts are automatically discovered and listed on the blog index page.