Spike: POC centralized design system docs repo integration with PatternFly infrastructure

[patternfly-jira-sync]

Spike: POC centralized design system docs repo integration with PatternFly infrastructure

Type: Spike / Technical Feasibility
Goal: Using the in-progress AI design standards docs as the first real content, stand up the proposed centralized documentation repository on Red Hat's enterprise GitHub (public) and prove that PatternFly can consume its markdown without imposing requirements that complicate consumption by other teams (digital/marketing DS, brand).

Problem Statement

Three teams (PatternFly, digital/marketing design system, brand) are converging on shared design standards — starting with AI design standards currently being drafted. Rather than duplicating this content across three doc sites, we want a single shared repository of markdown files.

PatternFly has a non-trivial documentation pipeline (Astro, MDX auto-conversion, frontmatter-driven routing, a REST API for AI agent consumption via patternfly-mcp). The other teams have entirely different infrastructure and expect to consume plain markdown files. We need to validate that:

1. A shared repo can stay simple enough for all consumers
2. PatternFly can adapt the content to its pipeline without requiring changes to the shared source files
3. The content flows through to patternfly.org rendering AND the doc-core API / patternfly-mcp

What We're Exploring

Question

How we'll answer it

What frontmatter can all three teams agree on?

Propose a minimal generic schema, validate it doesn't conflict with any team's pipeline

Can PF consume content that doesn't have PF-specific frontmatter (id, section)?

Build a small mapping/adapter layer and test it

Does plain prose markdown survive the full PF pipeline intact?

Add the AI design standards content as a doc-core content  and verify rendering + API output

Does centralized content appear correctly in patternfly-mcp?

Query the doc-core API for the centralized content and confirm it's discoverable

Can we consume a public repo on RH enterprise GH via npm?

Validate npm install from the git URL works in patternfly-org's CI

Spike Activities

4. Create the repo on Red Hat enterprise GitHub (public) with a minimal structure:

redhat-design-docs/
content/
ai/
ai-design-standards.md
...
package.json # name + version, enables npm install from git URL

5. Define a minimal frontmatter schema for shared content:

---                                                                                                                                                  
title: AI Design Standards
description: Guidelines for designing AI-powered experiences
category: guidelines                                                                                                                                 
subcategory: ai           # optional                                                                                                                 
tags: [ai, chatbot, llm]  # optional, for search/filtering                                                                                           
---                                                                                                                                                  
                                                

This is intentionally generic — no PF-specific fields (id, section, etc.).

6. Build a PF adapter — the smallest thing that works. Options to evaluate:

• A mapping config in patternfly-org that maps category to PF's section and derives id from title or filename

• A lightweight build script that generates PF-compatible frontmatter wrappers

• A small enhancement to patternfly-doc-core to support per-source frontmatter defaults/transforms in pf-docs.config.mjs (e.g.,
  frontmatterDefaults: { section: "ai" })

7. Wire it up — install the centralized repo via git URL and add a content entry to pf-docs.config.mjs:

// in package.json dependencies:                                                                                                                     
// "@redhat/design-docs": "git+<https://enterprise-gh-url/redhat-design-docs.git>"                                                                     
// in pf-docs.config.mjs:                                                                                                                            
{                                                                                                                                                    
  base: "../../node_modules/@redhat/design-docs",                                                                                                    
  pattern: "content/**/*.{md,mdx}",                                                                                                                  
  name: "centralized-design-docs"                                                                                                                    
}                                                                                                                                                    

8. Validate the full path:

• Content renders on patternfly.org in the correct section and navigation

• Content appears in the doc-core API index (GET /api/v6 should list the new section; GET /api/v6/{section} should list the AI design standards page)

• Content body is retrievable via GET /api/v6/{section}/{page}/text/text and returns the markdown prose

• patternfly-mcp can discover and return the centralized content when queried (e.g., asking the MCP about AI design standards returns relevant results)

• No changes were required to the centralized repo's markdown files to make any of the above work

9. **Check with the other teams — share the repo structure and frontmatter schema, confirm they can consume it with their infrastructure. **

Deliverables

• Working public repo on RH enterprise GitHub with AI design standards content

• Documented frontmatter schema with rationale

• POC branch on patternfly-org demonstrating the integration (installed via git URL, rendering correctly)

• Confirmed doc-core API serves the centralized content

• Documented any changes needed in patternfly-doc-core to support frontmatter mapping

• Summary of findings: what works, what's hard, what needs further investment

• Confirmed doc-core API serves the centralized content (document the exact API routes the content appears at)

• Confirmed patternfly-mcp returns centralized content when queried   

**Out of Scope **

• Full migration of existing shared content (this spike only uses AI design standards as the test case)

• Governance model, CODEOWNERS, contribution process (important, but separate discussion)

• CI/CD for automated npm registry publishing (git-based npm install is sufficient for the POC; registry publishing is a follow-up)

• Changes to the other teams' pipelines (they just need to confirm they can consume it)

**Risks & Open Questions **

• Frontmatter negotiation could stall if teams can't agree on a schema. Mitigation: start with the absolute minimum (title, category) and extend
  later.

• doc-core may need changes to support frontmatter defaults per content source. If so, size that work and decide whether it belongs in the spike or
  is a follow-up story.

• Tab assignment: doc-core assigns tabs based on package name. Content from a new package will default to the text tab, which is probably correct for
  guidance docs but worth verifying.

• npm install from git URL: need to confirm this works cleanly in patternfly-org's CI (GitHub Actions on public cloning from RH enterprise
  GH — should work since the repo is public, but needs validation).

• Who owns the centralized repo long-term? This spike doesn't need to answer that, but the answer affects everything downstream.

**PatternFly Infrastructure Context (Reference) **

For anyone unfamiliar with PF's doc pipeline:

• pf-docs.config.mjs defines content sources as {base, pattern, name} entries — there are already 15+ sources (react-core, react-table, chatbot,
  etc.)

• patternfly-doc-core auto-converts .md → .mdx at build time; plain prose markdown with no JSX works fine

• Frontmatter requires id and section at minimum for routing and API indexing — this is why a mapping/adapter layer is needed rather than putting
  PF-specific fields in the shared repo

• The doc-core REST API indexes all content and serves it as JSON, consumed by patternfly-mcp and other AI agents

• Adding a new content source is a one-line config change; the complexity is in frontmatter adaptation

---

Jira Issue: PF-4002