@patternfly/patternfly-doc-core 1.15.3 → 1.15.5

package/src/pages/api/openapi.json.ts

@@ -0,0 +1,398 @@
+import type { APIRoute } from 'astro'
+import { fetchApiIndex } from '../../utils/apiIndex/fetch'
+import { createJsonResponse } from '../../utils/apiHelpers'
+
+export const prerender = false
+
+export const GET: APIRoute = async ({ url }) => {
+  let versions: string[]
+  try {
+    const index = await fetchApiIndex(url)
+    versions = index.versions
+  } catch (error) {
+    const details = error instanceof Error ? error.message : String(error)
+    return createJsonResponse(
+      { error: 'Failed to load API index', details },
+      500
+    )
+  }
+
+  const openApiSpec = {
+    openapi: '3.0.0',
+    info: {
+      title: 'PatternFly Documentation API',
+      description:
+        'Machine-readable documentation API for LLM agents and MCP servers. Provides hierarchical access to PatternFly documentation content.',
+      version: '1.0.0',
+      contact: {
+        name: 'PatternFly',
+        url: 'https://patternfly.org',
+      },
+    },
+    servers: [
+      {
+        url: '/api',
+        description: 'Documentation API base path',
+      },
+    ],
+    paths: {
+      '/': {
+        get: {
+          summary: 'Get API documentation',
+          description:
+            'Returns self-documenting API schema with complete endpoint descriptions, parameters, and usage examples',
+          operationId: 'getApiDocs',
+          responses: {
+            '200': {
+              description: 'API documentation schema',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      name: { type: 'string' },
+                      description: { type: 'string' },
+                      version: { type: 'string' },
+                      baseUrl: { type: 'string' },
+                      endpoints: {
+                        type: 'array',
+                        items: { type: 'object' },
+                      },
+                      usage: { type: 'object' },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      '/versions': {
+        get: {
+          summary: 'List available versions',
+          description: 'Returns an array of available documentation versions',
+          operationId: 'getVersions',
+          responses: {
+            '200': {
+              description: 'List of available versions',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'array',
+                    items: {
+                      type: 'string',
+                    },
+                    example: versions,
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      '/openapi.json': {
+        get: {
+          summary: 'Get OpenAPI specification',
+          description: 'Returns the complete OpenAPI 3.0 specification for this API',
+          operationId: 'getOpenApiSpec',
+          responses: {
+            '200': {
+              description: 'OpenAPI 3.0 specification',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    description: 'Full OpenAPI 3.0 specification',
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      '/{version}': {
+        get: {
+          summary: 'List sections for a version',
+          description:
+            'Returns an array of available documentation sections for the specified version',
+          operationId: 'getSections',
+          parameters: [
+            {
+              name: 'version',
+              in: 'path',
+              required: true,
+              description: 'Documentation version',
+              schema: {
+                type: 'string',
+                enum: versions,
+              },
+              example: 'v6',
+            },
+          ],
+          responses: {
+            '200': {
+              description: 'List of available sections',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'array',
+                    items: {
+                      type: 'string',
+                    },
+                  },
+                  example: ['components', 'layouts', 'utilities'],
+                },
+              },
+            },
+            '404': {
+              description: 'Version not found',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      error: {
+                        type: 'string',
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      '/{version}/{section}': {
+        get: {
+          summary: 'List pages in a section',
+          description:
+            'Returns an array of page IDs within the specified section',
+          operationId: 'getPages',
+          parameters: [
+            {
+              name: 'version',
+              in: 'path',
+              required: true,
+              description: 'Documentation version',
+              schema: {
+                type: 'string',
+                enum: versions,
+              },
+              example: 'v6',
+            },
+            {
+              name: 'section',
+              in: 'path',
+              required: true,
+              description: 'Documentation section',
+              schema: {
+                type: 'string',
+              },
+              example: 'components',
+            },
+          ],
+          responses: {
+            '200': {
+              description: 'List of page IDs (kebab-cased)',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'array',
+                    items: {
+                      type: 'string',
+                    },
+                  },
+                  example: ['alert', 'button', 'card'],
+                },
+              },
+            },
+            '404': {
+              description: 'Section not found',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      error: {
+                        type: 'string',
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      '/{version}/{section}/{page}': {
+        get: {
+          summary: 'List tabs for a page',
+          description:
+            'Returns an array of available tab slugs for the specified page',
+          operationId: 'getTabs',
+          parameters: [
+            {
+              name: 'version',
+              in: 'path',
+              required: true,
+              description: 'Documentation version',
+              schema: {
+                type: 'string',
+                enum: versions,
+              },
+              example: 'v6',
+            },
+            {
+              name: 'section',
+              in: 'path',
+              required: true,
+              description: 'Documentation section',
+              schema: {
+                type: 'string',
+              },
+              example: 'components',
+            },
+            {
+              name: 'page',
+              in: 'path',
+              required: true,
+              description: 'Page ID (kebab-cased)',
+              schema: {
+                type: 'string',
+              },
+              example: 'alert',
+            },
+          ],
+          responses: {
+            '200': {
+              description: 'List of available tab slugs',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'array',
+                    items: {
+                      type: 'string',
+                    },
+                  },
+                  example: ['react', 'react-demos', 'html'],
+                },
+              },
+            },
+            '404': {
+              description: 'Page not found',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      error: {
+                        type: 'string',
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      '/{version}/{section}/{page}/{tab}': {
+        get: {
+          summary: 'Get tab content',
+          description:
+            'Returns the raw markdown/MDX documentation content for the specified tab',
+          operationId: 'getContent',
+          parameters: [
+            {
+              name: 'version',
+              in: 'path',
+              required: true,
+              description: 'Documentation version',
+              schema: {
+                type: 'string',
+                enum: versions,
+              },
+              example: 'v6',
+            },
+            {
+              name: 'section',
+              in: 'path',
+              required: true,
+              description: 'Documentation section',
+              schema: {
+                type: 'string',
+              },
+              example: 'components',
+            },
+            {
+              name: 'page',
+              in: 'path',
+              required: true,
+              description: 'Page ID (kebab-cased)',
+              schema: {
+                type: 'string',
+              },
+              example: 'alert',
+            },
+            {
+              name: 'tab',
+              in: 'path',
+              required: true,
+              description: 'Tab slug',
+              schema: {
+                type: 'string',
+              },
+              example: 'react',
+            },
+          ],
+          responses: {
+            '200': {
+              description: 'Raw markdown/MDX content',
+              content: {
+                'text/plain; charset=utf-8': {
+                  schema: {
+                    type: 'string',
+                  },
+                  example:
+                    '---\ntitle: Alert\nsection: components\n---\n\n## Overview\n\nAn alert is a notification that provides...',
+                },
+              },
+            },
+            '404': {
+              description: 'Tab not found',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      error: {
+                        type: 'string',
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    tags: [
+      {
+        name: 'Documentation',
+        description: 'PatternFly documentation endpoints',
+      },
+    ],
+  }
+
+  const body = JSON.stringify(openApiSpec, null, 2)
+  return new Response(body, {
+    status: 200,
+    headers: {
+      'Content-Type': 'application/json; charset=utf-8',
+      'Cache-Control': 'no-cache',
+      Date: new Date().toUTCString(),
+      'Content-Length': body.length.toString(),
+    },
+  })
+}

package/src/pages/api/versions.ts

@@ -0,0 +1,17 @@
+import type { APIRoute } from 'astro'
+import { createJsonResponse } from '../../utils/apiHelpers'
+import { fetchApiIndex } from '../../utils/apiIndex/fetch'
+
+export const prerender = false
+
+export const GET: APIRoute = async ({ url }) => {
+  try {
+    const index = await fetchApiIndex(url)
+    return createJsonResponse(index.versions)
+  } catch (error) {
+    return createJsonResponse(
+      { error: 'Failed to load API index', details: error },
+      500
+    )
+  }
+}

package/src/pages/apiIndex.json.ts

@@ -0,0 +1,27 @@
+import type { APIRoute } from 'astro'
+import { getApiIndex } from '../utils/apiIndex/get'
+
+// Prerender at build time so this doesn't run in the Cloudflare Worker
+export const prerender = true
+
+export const GET: APIRoute = async () => {
+  try {
+    const index = await getApiIndex()
+    return new Response(JSON.stringify(index), {
+      status: 200,
+      headers: {
+        'Content-Type': 'application/json',
+      },
+    })
+  } catch (error) {
+    return new Response(
+      JSON.stringify({ error: 'Failed to load API index', details: error }),
+      {
+        status: 500,
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      }
+    )
+  }
+}

package/src/utils/apiHelpers.ts

@@ -0,0 +1,50 @@
+function getHeaders(
+  type: 'application/json' | 'text/plain',
+  contentLength?: number,
+): HeadersInit {
+  const headers: HeadersInit = {
+    'Content-Type': `${type}; charset=utf-8`,
+    'Cache-Control': 'no-cache',
+    Date: new Date().toUTCString(),
+  }
+
+  if (contentLength) {
+    headers['Content-Length'] = contentLength.toString()
+  }
+
+  return headers
+}
+
+export function createJsonResponse(
+  data: unknown,
+  status: number = 200,
+): Response {
+  const body = JSON.stringify(data)
+  return new Response(body, {
+    status,
+    headers: getHeaders('application/json', body.length),
+  })
+}
+
+export function createTextResponse(
+  content: string,
+  status: number = 200,
+): Response {
+  return new Response(content, {
+    status,
+    headers: getHeaders('text/plain', content.length),
+  })
+}
+
+/**
+ * Creates an index key by joining parts with '::' separator
+ * Used to construct keys for looking up sections, pages, and tabs in the API index
+ *
+ * @example
+ * createIndexKey('v6') // 'v6'
+ * createIndexKey('v6', 'components') // 'v6::components'
+ * createIndexKey('v6', 'components', 'alert') // 'v6::components::alert'
+ */
+export function createIndexKey(...parts: string[]): string {
+  return parts.join('::')
+}

package/src/utils/apiIndex/fetch.ts

@@ -0,0 +1,20 @@
+import type { ApiIndex } from './generate'
+
+/**
+ * Fetches the API index from the server as a static asset
+ * Used by API routes at runtime instead of importing the JSON statically
+ *
+ * @param url - The URL object from the API route context
+ * @returns Promise resolving to the API index structure
+ */
+export async function fetchApiIndex(url: URL): Promise<ApiIndex> {
+  const apiIndexUrl = new URL('/apiIndex.json', url.origin)
+  const response = await fetch(apiIndexUrl)
+
+  if (!response.ok) {
+    throw new Error(`Failed to load API index: ${response.status} ${response.statusText}`)
+  }
+
+  const data = (await response.json()) as ApiIndex
+  return data
+}

package/src/utils/apiIndex/generate.ts

@@ -0,0 +1,164 @@
+/* eslint-disable no-console */
+import { join } from 'path'
+import { writeFile, mkdir } from 'fs/promises'
+import { getCollection } from 'astro:content'
+import type { CollectionKey } from 'astro:content'
+import { content } from '../../content'
+import { kebabCase, addDemosOrDeprecated } from '../index'
+import { getDefaultTabForApi } from '../packageUtils'
+import { getOutputDir } from '../getOutputDir'
+
+const SOURCE_ORDER: Record<string, number> = {
+  react: 1,
+  'react-next': 1.1,
+  'react-demos': 2,
+  'react-deprecated': 2.1,
+  html: 3,
+  'html-demos': 4,
+  'design-guidelines': 99,
+  accessibility: 100,
+  'upgrade-guide': 101,
+  'release-notes': 102,
+}
+
+const sortSources = (s1: string, s2: string) => {
+  const s1Index = SOURCE_ORDER[s1] || 50
+  const s2Index = SOURCE_ORDER[s2] || 50
+  if (s1Index === 50 && s2Index === 50) {
+    return s1.localeCompare(s2)
+  }
+  return s1Index > s2Index ? 1 : -1
+}
+
+/**
+ * Structure of the API index used for routing and navigation
+ * Keys in sections/pages/tabs use '::' separator (e.g., 'v6::components::alert')
+ */
+export interface ApiIndex {
+  /** Available documentation versions (e.g., ['v5', 'v6']) */
+  versions: string[]
+  /** Sections by version (e.g., { 'v6': ['components', 'layouts'] }) */
+  sections: Record<string, string[]>
+  /** Pages by version::section (e.g., { 'v6::components': ['alert', 'button'] }) */
+  pages: Record<string, string[]>
+  /** Tabs by version::section::page (e.g., { 'v6::components::alert': ['react', 'html'] }) */
+  tabs: Record<string, string[]>
+}
+
+/**
+ * Generates API index by analyzing all content collections
+ * Extracts versions, sections, pages, and tabs into a hierarchical structure
+ * This runs during build time when getCollection() is available
+ *
+ * @returns Promise resolving to complete API index structure
+ */
+export async function generateApiIndex(): Promise<ApiIndex> {
+  console.log('Generating API index from content collections...')
+
+  const index: ApiIndex = {
+    versions: [],
+    sections: {},
+    pages: {},
+    tabs: {},
+  }
+
+  // Get all versions
+  const versionSet = new Set<string>()
+  content.forEach((entry: any) => {
+    if (entry.version) {
+      versionSet.add(entry.version)
+    }
+  })
+  index.versions = Array.from(versionSet).sort()
+
+  // For each version, collect index data
+  for (const version of versionSet) {
+    const collectionsToFetch = content
+      .filter((entry: any) => entry.version === version)
+      .map((entry: any) => entry.name as CollectionKey)
+
+    const collections = await Promise.all(
+      collectionsToFetch.map((name) => getCollection(name)),
+    )
+
+    const flatEntries = collections.flat()
+
+    // Collect sections, pages, and tabs in a single pass
+    const sections = new Set<string>()
+    const sectionPages: Record<string, Set<string>> = {}
+    const pageTabs: Record<string, Set<string>> = {}
+
+    flatEntries.forEach((entry: any) => {
+      if (!entry.data.section) {
+        return
+      }
+
+      const section = entry.data.section
+      const page = kebabCase(entry.data.id)
+      const sectionKey = `${version}::${section}`
+      const pageKey = `${version}::${section}::${page}`
+
+      // Collect section
+      sections.add(section)
+
+      // Collect page
+      if (!sectionPages[sectionKey]) {
+        sectionPages[sectionKey] = new Set()
+      }
+      sectionPages[sectionKey].add(page)
+
+      // Collect tab
+      const entryTab =
+        entry.data.tab || entry.data.source || getDefaultTabForApi(entry.filePath)
+      const tab = addDemosOrDeprecated(entryTab, entry.id)
+      if (!pageTabs[pageKey]) {
+        pageTabs[pageKey] = new Set()
+      }
+      pageTabs[pageKey].add(tab)
+    })
+
+    // Convert sets to sorted arrays
+    index.sections[version] = Array.from(sections).sort()
+
+    Object.entries(sectionPages).forEach(([key, pages]) => {
+      index.pages[key] = Array.from(pages).sort()
+    })
+
+    Object.entries(pageTabs).forEach(([key, tabs]) => {
+      index.tabs[key] = Array.from(tabs).sort(sortSources)
+    })
+  }
+
+  return index
+}
+
+/**
+ * Writes API index to a apiIndex.json file in the user defined output directory
+ * This file is used by server-side API routes to avoid runtime getCollection() calls
+ *
+ * @param index - The API index structure to write
+ */
+export async function writeApiIndex(index: ApiIndex): Promise<void> {
+  const outputDir = await getOutputDir()
+  const indexPath = join(outputDir, 'apiIndex.json')
+
+  try {
+    await mkdir(outputDir, { recursive: true })
+    await writeFile(indexPath, JSON.stringify(index, null, 2))
+    console.log(`✓ Generated API index with ${index.versions.length} versions`)
+  } catch (error) {
+    console.warn('Warning: Could not write API index file:', error)
+  }
+}
+
+/**
+ * Generates and writes API index in a single operation
+ * Called during build in getStaticPaths to ensure index exists for server routes
+ *
+ * @returns Promise resolving to the generated API index
+ */
+export async function generateAndWriteApiIndex(): Promise<ApiIndex> {
+  const index = await generateApiIndex()
+  await writeApiIndex(index)
+  return index
+}