This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Apache Iggy website -- a static documentation and marketing site built with Next.js + Fumadocs + Tailwind CSS (versions pinned in package.json). Output is a fully static export (no server runtime).
npm install # Install deps (triggers fumadocs-mdx postinstall)
npm run dev # Dev server with hot reload (http://localhost:3000)
npm run build # Static export to out/ directory
npx serve out # Preview the static buildnpm start (next start) does not work here: it is incompatible with output: "export". predev/prebuild run scripts/fetch-github-stars.mjs (network call with a graceful offline fallback).
No test framework is configured. No linter is configured beyond TypeScript strict mode.
Tech stack: Next.js App Router, Fumadocs (docs framework), Tailwind CSS v4, MDX, TypeScript.
Route groups:
src/app/(home)/-- Landing page with hero, features, footersrc/app/(site)/-- Blog listing (/blogs/), downloads (/downloads/), community (/community/)src/app/docs/-- Documentation pages via Fumadocs DocsLayoutsrc/app/api/search/-- Static search index (search UI enabled in the docs layout)
Content (MDX):
content/docs/-- Documentation pages, structured viameta.jsonfiles for ordering/hierarchycontent/blog/-- Blog posts with frontmatter (title, author, date, tags, draft). Date-based URL routing:/blogs/YYYY/MM/DD/[slug]
Shared config: src/lib/layout.shared.tsx defines navigation options (homeOptions, siteOptions, docsOptions) shared across all layouts.
Content loading: src/lib/source.ts configures the Fumadocs source loader. Blog and docs collections are defined in source.config.ts at the project root.
Static output: next.config.mjs sets output: "export", trailingSlash: true, and images: { unoptimized: true }.
- New docs pages MUST be listed in their directory's
meta.jsonpagesarray or they build fine but never appear in the sidebar (nometa.jsonuses the"..."rest item). Docs frontmatter requirestitle. - Static export means no redirects, rewrites, middleware, or runtime API routes. Renaming or moving a page breaks its URL permanently; think before renaming. New dynamic route segments need
generateStaticParams. - Every new
.ts/.tsx/.mjs/.cssfile needs the Apache 2.0 license header. MDX content does not. - Custom docs components (architecture diagrams, Mermaid) are registered globally in
src/mdx-components.tsx; use them in MDX without imports. Diagram components live insrc/components/architecture-diagrams.tsx. - Dark theme is the default (the home page force-locks dark; docs pages have a light/dark toggle, test both). Palette source of truth: CSS variables in
src/app/global.css. - Client components must be marked with
"use client". - Mermaid diagrams are supported in MDX via
src/components/mermaid.tsx(client-rendered, theme-aware). - Blog frontmatter schema is defined in
source.config.tsusing Zod. - Node.js v26+ required (
.nvmrc). .npmrcsetslegacy-peer-deps=true.- Commits follow conventional commits:
type(scope): subject, e.g.fix(docs): .... scripts/generate-docs-markdown.mjswrites a Markdown copy of every docs page and blog post (its URL plus.md) before each dev and build run.src/app/llms.txt/route.ts,src/app/llms-full.txt/route.tsandsrc/app/llms-full/[section]/route.ts(one file per docs section) build on those copies, throughsrc/lib/llms.ts. The copies keep code fences as written, so give every fence a language. Site-relative links become absolute.- A diagram component used on its own line in MDX is replaced in the Markdown copy by its text in
scripts/diagram-text.mjs. When you add or change a diagram, add or update its text there. The generator fails if a component has no text. - The docs version shown in llms.txt, llms-full.txt and the Markdown copies is set in
src/lib/docs-version.json. Update it when the docs move to a new release.
content/docs-0.8/is a frozen copy of the docs as they stood for Apache Iggy 0.8 (commit9eece0aa, before the 0.9.0 update), served at/docs/0.8bysrc/app/(archive)/docs/0.8/. The current docs live insrc/app/(current)/docs/; the route groups keep the two sidebars apart.- Do not edit the archive except to fix something broken. Its
/docslinks point at/docs/0.8, andnpm run check:linksfails if an archived page links outside it. - The archive uses its own copy of the diagrams in
src/components/archive-0.8/, shows a notice on every page, is markednoindex, and is left out of search, the sitemap and llms.txt, which all usesourcerather thansource08.
- Default branch is
main(the code repo usesmaster; this one does not). - Push to
maintriggers.github/workflows/deploy.yml(also daily cron and manual dispatch), which builds and force-orphan-pushesout/to theasf-sitebranch -> iggy.apache.org. - Push to
stagingtriggersstage.yml, same flow toasf-staging-> iggy.staged.apache.org. Use it to preview large changes. asf-siteandasf-stagingare generated artifacts. Never edit them by hand.- Both workflows copy
.asf.yamland.htaccessintoout/before publishing. The.htaccesssetsErrorDocument 404 /404.html; without it the ASF web server answers unknown paths with its own bare "Not Found" body instead of the site's 404 page (the status code is 404 either way). - Branch-to-URL mapping is configured via
.asf.yaml(Apache infrastructure).
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.
This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.