# How GraphQL API Documentation Synchronization Works in GitHub Docs

> Learn how GitHub Docs synchronizes GraphQL API documentation by auto-generating reference pages from JSON schema during the Nextjs build process using PageTransformers.

- Repository: [GitHub/docs](https://github.com/github/docs)
- Tags: internals
- Published: 2026-06-01

---

**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`](https://github.com/github/docs/blob/main/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`](https://github.com/github/docs/blob/main/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`](https://github.com/github/docs/blob/main/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`](https://github.com/github/docs/blob/main/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`](https://github.com/github/docs/blob/main/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:
   ```yaml
   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`](https://github.com/github/docs/blob/main/.../graphql/reference/index.md)

4. **Schema Loading**: Inside `GraphQLReferenceTransformer.transform`, the utilities are imported dynamically and invoked:
   ```typescript
   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`](https://github.com/github/docs/blob/main/graphql-reference.template.md) or [`graphql-index.template.md`](https://github.com/github/docs/blob/main/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:

```typescript
// 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`](https://github.com/github/docs/blob/main/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`](https://github.com/github/docs/blob/main/src/article-api/transformers/graphql-index-transformer.ts): Navigation index generation
- [`src/article-api/lib/graphql-helpers.ts`](https://github.com/github/docs/blob/main/src/article-api/lib/graphql-helpers.ts): Manual content extraction utilities
- [`src/graphql/lib/index.ts`](https://github.com/github/docs/blob/main/src/graphql/lib/index.ts): Centralized schema loading and caching
- [`src/article-api/templates/graphql-reference.template.md`](https://github.com/github/docs/blob/main/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`](https://github.com/github/docs/blob/main/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`](https://github.com/github/docs/blob/main/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`](https://github.com/github/docs/blob/main/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.