Add way to build only the API

[wise-king-sullyman]

Problem Summary

The current build process builds the entire documentation site, including all HTML pages and API routes. For use cases that only require the API endpoints (JSON responses), this results in unnecessary build time and output size.

Current limitation: The pf-doc-core build command builds everything with no option to selectively build only the API routes.

Use Case

In the context of only needing the API portion of doc-core, an API-only build would provide:

• Faster build times: Skip rendering 300+ HTML documentation pages
• Smaller output size: Reduce from 68MB to just the API routes and supporting files
• Simpler deployments: Deploy only the API infrastructure without the full documentation site
• Resource efficiency: Lower build resource requirements for API-only services

Example scenario: A service that consumes the PatternFly component data via the API endpoints doesn't need the visual documentation pages, only the JSON responses.

Current Architecture

The build process (cli/cli.ts:115-158) performs a complete Astro build:

// cli/cli.ts:138-141
await build({
  root: astroRoot,
  outDir: docsOutputDir,
})

What gets built:

• API routes (src/pages/api/**): JSON endpoints for components, tokens, props, examples, etc.
• Documentation pages (src/pages/[section]/): 326 HTML pages for components, layouts, patterns, utilities
• Static assets: Images, CSS, JavaScript bundles
• Supporting files: apiIndex.json, props.json

Build output structure:

dist/docs/
├── api/                    # API routes (needed)
│   └── v6/
├── components/             # HTML pages (not needed for API-only)
├── layouts/                # HTML pages (not needed for API-only)
├── patterns/               # HTML pages (not needed for API-only)
├── utility-classes/        # HTML pages (not needed for API-only)
├── _astro/                 # Assets bundle
├── apiIndex.json           # Needed for API
├── props.json              # Needed for API
└── index.html              # Root page (not needed for API-only)

Completion Criteria

The issue is resolved when:

1. API-only build command: A new CLI command (e.g., build:api or build --api-only) that builds only the API routes
2. Reduced build output: API-only build produces only the necessary files:
   • /api/** routes
   • apiIndex.json
   • props.json
   • Minimal assets/worker files needed for API functionality
3. Faster build time: Measurably faster build compared to full site build
4. Smaller output: Significantly reduced output directory size
5. Backward compatibility: Existing build command continues to work for full site builds
6. Deployment compatibility: API-only builds work with the current Cloudflare adapter and deployment process

Technical Notes

• Current full build: 326 HTML pages, 68MB output size
• API routes location: src/pages/api/** (20 route files)
• Documentation pages: src/pages/[section]/ (all other routes)
• Build command: cli/cli.ts:115-158
• Supporting data files needed: apiIndex.json (generated), props.json (generated)
• Both prerendered (prerender = true) and server-rendered (prerender = false) API routes exist

Related Links

• Jira: PF-3600