How GraphQL API Documentation Synchronization Works in GitHub Docs

GraphQL API documentation synchronization in github/docs works by auto-generating reference pages from version-specific JSON schema files during the Next.js build pipeline, using PageTransformers to render Markdown templates.

The github/docs repository maintains its GraphQL reference documentation through an automated synchronization process that transforms raw schema JSON into human-readable Markdown. This system ensures the public documentation stays current with the live GitHub GraphQL API without requiring manual updates to individual pages. Understanding this GraphQL API documentation synchronization architecture reveals how the repository bridges internal API changes with published documentation.

Core Components of the Synchronization Architecture

Version-Specific Schema Files

Raw GraphQL schemas, changelogs, and preview data live in src/graphql/data/<version>/ as JSON files (e.g., schema-repos.json). These files are produced by internal tooling that introspects the live GraphQL API and are the single source of truth for the documentation content.

GraphQL Library Utilities

The src/graphql/lib/index.ts module provides cached access to schema data through utility functions. Key exports include getGraphqlSchema(version, pageType), which lazily reads category-specific JSON files, and getAllGraphqlObjects(version), which loads the complete object map. The library caches results to optimize build performance across multiple page generations.

Page Transformers

Two specialized transformers handle the conversion from schema data to documentation:

• GraphQLReferenceTransformer (src/article-api/transformers/graphql-reference-transformer.ts): Processes category-specific reference pages (queries, mutations, objects) by iterating over schema buckets for a given category slug.
• GraphQLIndexTransformer (src/article-api/transformers/graphql-index-transformer.ts): Generates the top-level navigation index linking all category pages.

Manual Content Preservation

The src/article-api/lib/graphql-helpers.ts file contains extractManualContent, which identifies content appearing before the marker <!-- Content after this section is automatically generated -->. This allows authors to add custom introductions that persist across automated updates.

The Synchronization Workflow Step-by-Step

1. Schema Update: Internal tooling updates JSON files in src/graphql/data/<version>/ to reflect the current GraphQL API state.

2. Build Initialization: The Next.js build invokes the article-api pipeline, which scans for Markdown files containing the frontmatter:

   autogenerated: graphql

3. Transformer Selection: The pipeline calls canTransform to route pages to the appropriate handler:

   • GraphQLReferenceTransformer matches reference pages where !page.relativePath.endsWith('index.md')
   • GraphQLIndexTransformer matches the sole index page at .../graphql/reference/index.md

4. Schema Loading: Inside GraphQLReferenceTransformer.transform, the utilities are imported dynamically and invoked:

   const { getGraphqlSchema, getAllGraphqlObjects } = await import('@/graphql/lib/index')
   const schema = getGraphqlSchema(currentVersion, pageType)
   const allObjects = getAllGraphqlObjects(currentVersion)

5. Item Preparation: For each kind (queries, mutations, objects, enums), the transformer calls prepareByKind to normalize fields, extract descriptions using fastTextOnly, build kind-disambiguated slugs, and append auxiliary data like interface implementers.

6. Manual Content Extraction: extractManualContent parses the source file to capture any custom Markdown written before the auto-generation marker.

7. Template Rendering: The transformed data merges with Liquid templates (graphql-reference.template.md or graphql-index.template.md) via renderContent, producing final Markdown with variables including pageTitle, pageIntro, manualContent, and items.

8. Build Output: The generated Markdown is written to the static build folder. Because this runs on every CI build, schema changes propagate immediately to the published documentation.

Rendering Implementation Details

The reference transformer builds a flat, alphabetically sorted list of all items across kinds before rendering:

// Inside GraphQLReferenceTransformer.transform(...)
const schema = getGraphqlSchema(currentVersion, pageType)
const allObjects = getAllGraphqlObjects(currentVersion)

for (const kind of ALL_KIND_KEYS) {
  const items = schema[kind] ?? []
  const prepared = await Promise.all(
    items.map(item => this.prepareByKind(kind, item, allObjects, KIND_SLUG_PREFIX[kind]))
  )
  flatEntries.push(...prepared.map(p => ({ kind, item: p })))
}
flatEntries.sort(/* alphabetical + kind tiebreaker */)

const template = loadTemplate('graphql-reference.template.md')
return renderContent(template, {
  pageTitle: page.title,
  pageIntro: intro,
  manualContent,
  items: flatEntries.map(e => e.item),
  markdownRequested: true,
})

Key Files for Understanding the Implementation

• src/article-api/transformers/graphql-reference-transformer.ts: Core logic for building reference pages from schema categories
• src/article-api/transformers/graphql-index-transformer.ts: Navigation index generation
• src/article-api/lib/graphql-helpers.ts: Manual content extraction utilities
• src/graphql/lib/index.ts: Centralized schema loading and caching
• src/article-api/templates/graphql-reference.template.md: Liquid template defining the final page structure

Summary

• GraphQL documentation in github/docs is auto-generated from JSON schema files stored in src/graphql/data/<version>/
• The article-api pipeline processes pages marked with autogenerated: graphql frontmatter during every build
• GraphQLReferenceTransformer and GraphQLIndexTransformer convert schema data into Markdown using Liquid templates
• Manual content can precede auto-generated sections via the HTML comment marker parsed by src/article-api/lib/graphql-helpers.ts
• The continuous integration pipeline ensures documentation stays synchronized with the live GraphQL API without manual intervention

Frequently Asked Questions

How does the build system know which pages to auto-generate?

The article-api pipeline checks the frontmatter of every Markdown file. Pages containing autogenerated: graphql are flagged for processing by the GraphQL transformers during the site build. The canTransform method in each transformer then determines whether it handles the specific page based on the file path.

Can I edit the text on a GraphQL reference page manually?

You can add custom introductions by placing Markdown content before the comment <!-- Content after this section is automatically generated --> in the source file. The extractManualContent function preserves this text while replacing everything after the marker with fresh schema data generated from the current JSON files.

Where does the actual GraphQL schema data come from?

The JSON files in src/graphql/data/<version>/ (such as schema-repos.json) are produced by internal GitHub tooling that introspects the live GraphQL API. These files are committed to the repository and drive the documentation generation through functions like getGraphqlSchema in src/graphql/lib/index.ts.

What happens if the GraphQL schema changes?

When the underlying JSON schema files are updated in the repository, the next build automatically reflects those changes. The synchronization pipeline runs on every CI build, meaning the getGraphqlSchema function loads the current version and the transformers render updated documentation without requiring manual edits to individual Markdown pages.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}