Add support for consumer side customization of the actual astro config

[wise-king-sullyman]

Problem Summary

Consumers cannot customize the Astro configuration from their side. The framework uses a hardcoded astro.config.mjs file within the doc-core package, preventing users from:

• Adding custom Astro integrations
• Modifying Vite configuration for their specific needs
• Changing the deployment adapter (currently hardcoded to Cloudflare)
• Customizing build settings, output options, or other Astro configurations

Current limitation: While users can customize content via pf-docs.config.mjs, they cannot modify the actual Astro config without forking doc-core and requesting npm releases.

Use Cases

Consumers need to customize Astro config for:

1. Deployment targets: Different hosting platforms (AWS, Netlify, Vercel) require different adapters
2. Vite configuration: Custom resolve aliases, plugins, or build optimizations
3. Integrations: Adding sitemap, analytics, or other Astro integrations
4. Performance tuning: Customizing bundle splitting, compression, or caching strategies
5. Environment-specific settings: Different configs for dev/staging/production

Current Architecture

The CLI currently modifies the Astro config via string replacement in setFsRootDir() (cli/setFsRootDir.ts:17-19), which is brittle and doesn't support general user customization.

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

The CLI invokes Astro's programmatic API with the hardcoded astroRoot config location. Consumers have no way to inject or merge their own configuration.

Completion Criteria

The issue is resolved when:

1. User config file supported: Consumers can create an optional Astro config file that gets merged with the base config
2. Configuration merging: User config is properly merged with doc-core's base config
3. Backward compatibility: Existing setups without user config continue to work with default behavior
4. Clear precedence rules: Documentation clearly explains which config values take precedence (user overrides vs. base defaults)
5. Type safety: User config gets proper TypeScript support and validation
6. All CLI commands supported: Config merging works for start, build, preview, and other commands
7. No string manipulation: Replace the brittle string replacement approach in setFsRootDir() with proper config merging

Technical Notes

• Astro 5.4.0+ supports mergeConfig() for configuration merging (docs)
• The CLI already uses Astro's programmatic API (build(), dev(), preview())
• inlineConfig parameter in programmatic API allows config override
• File locations: cli/cli.ts:138-141, cli/setFsRootDir.ts
• Current string replacement hack: cli/setFsRootDir.ts:17-19

Related Links

• Related issue: Add ability to pass in vite / astro configurations for doc core #95 (Add ability to pass in vite / astro configurations for doc core) - CLOSED
• Jira: PF-3604
• Astro mergeConfig API: https://docs.astro.build/en/reference/modules/astro-config/
• Astro programmatic API: https://docs.astro.build/en/reference/programmatic-reference/

[coderabbitai]

⚠️ Possible Duplicate Issue(s)

• Add ability to pass in vite / astro configurations for doc core #95

🔗 Related PRs

#197 - fix(config): address bug preventing custom scope usage [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!