Sync docs across repositories

Use this when one repository owns package code and MDX, but another repository owns the rendered docs UI. Start with a remote collection pinned in the docs UI repo, inherit the source-owned docs config, then choose how that pin gets updated.

The important part is not repository_dispatch. The important part is that the docs UI repo has a durable Leadtype remote collection that says exactly which source revision to render:

defineCollection({
  repository: "https://github.com/acme/sdk",
  ref: "f4e3c2d1",
  cacheDir: ".docs-src/sdk",
  dir: "docs",
  prefix: "/docs",
  sourceConfig: true,
});

That remote collection makes docs deploys reproducible. If 1.0.0 is live and main is halfway to 2.0.0, a Vercel, Cloudflare Pages, Netlify, self-hosted CI, or local redeploy still renders the 1.0.0 docs.

The ownership model is intentionally narrow:

• Source repo owns MDX, navigation/sidebar order, fallback groups, frontmatter schema, and source-specific flatteners.
• Docs UI repo owns product identity as rendered by the site, organization, agent policy, source repository/ref, output paths, hosting, analytics, and the app shell.

Recommended flow

The safest default is a manual promotion:

1. Release the package from the source repo.
2. Update the remote collection ref in the docs UI repo to the release commit SHA.
3. Open a PR in the docs UI repo.
4. Review the docs preview.
5. Merge the PR to deploy production docs.

This keeps production docs as an explicit promotion step. It is provider-neutral and easy to debug because the docs UI repo records the exact source revision it is rendering.

Configure the remote collection

Keep the source repo and commit SHA in leadtype.config.ts:

import { defineCollection, defineDocsConfig } from "leadtype";

export default defineDocsConfig({
  product: {
    name: "Acme",
    tagline: "Docs for Acme SDKs and platform APIs.",
  },
  collections: {
    docs: defineCollection({
      repository: "https://github.com/acme/sdk",
      ref: "f4e3c2d1",
      cacheDir: ".docs-src/sdk",
      dir: "docs",
      prefix: "/docs",
      sourceConfig: true,
    }),
  },
});

With sourceConfig: true, the source repo keeps the docs-specific config that belongs with the content: navigation, legacy groups, frontmatterSchema, source-specific flatteners, and same-tree mounts such as docs/changelog -> /changelog. The docs UI repo keeps the deployment pin and site-owned fields: repository, ref, cacheDir, product identity as rendered by the site, organization, agent policy, output directory, base URL, and the app shell.

Then sync and generate before the framework build:

{
  "scripts": {
    "docs:generate": "leadtype generate --src . --out public --base-url https://docs.example.com --sync",
    "build": "bun run docs:generate && next build"
  }
}

Use the same script shape for Astro, Nuxt, SvelteKit, TanStack Start, Vite, or a static file deploy. The framework only needs to render the human docs UI and serve the generated files.

Use leadtype generate --offline in CI jobs or local checks that must never touch the network. Offline generation still loads the inherited source config from the existing cache, and fails if the configured ref is not already synced.

If the docs UI repo uses the released package at build time, pin that dependency to the same version in the same PR and refresh the lockfile. That pins both the docs content and the package code used to render or generate it.

How Leadtype dogfoods this

The framework apps in apps/* are integration examples. The production Leadtype docs site is a separate docs UI app that renders leadtype.dev and syncs the Leadtype source repository into .leadtype.

Before sourceConfig, that app needed a custom source file (leadtype-source.json), a custom clone script, and a custom import of .leadtype/docs/docs.config.ts to reuse the source-owned navigation. With sourceConfig: true, the app can move that source ownership into first-class Leadtype config:

import { defineCollection, defineDocsConfig } from "leadtype";

export default defineDocsConfig({
  product: {
    name: "Leadtype",
    tagline:
      "Framework-neutral docs pipeline tooling for MDX, LLM bundles, and search.",
    docs: "https://leadtype.dev/docs",
    repository: "https://github.com/inthhq/leadtype",
    kind: "library",
  },
  organization: {
    name: "Inth",
    url: "https://inth.com",
  },
  collections: {
    docs: defineCollection({
      repository: "https://github.com/inthhq/leadtype",
      ref: "leadtype@0.1.2",
      cacheDir: ".leadtype",
      dir: "docs",
      prefix: "/docs",
      sourceConfig: true,
    }),
  },
});

The source repo keeps docs/docs.config.ts, MDX, navigation, groups, frontmatter schema, source-specific flatteners, and mounts. The Leadtype docs UI app keeps the app shell, consent, analytics, search UI, package dependency pin, and production source ref.

Optional automation: open the pin PR

Automation is useful when you want every package release to propose a docs update. In that setup, repository_dispatch is only the cross-repo notification. The docs UI repo still opens a PR and waits for review.

Dispatch a small immutable payload after publish:

{
  "repo": "acme/sdk",
  "sha": "f4e3c2d1...",
  "version": "1.0.0"
}

repo and sha are enough to fetch the exact docs. version is useful for PR titles, dependency pins, build logs, and release dashboards.

Source repo release workflow

Dispatch after the package publish step succeeds. A fine-grained token or GitHub App token needs write access to contents on the target docs repo because the GitHub API treats repository_dispatch as a write operation. Keep the target workflow on the docs repo's default branch; GitHub only starts repository_dispatch workflows from there.

name: Release

on:
  push:
    branches:
      - main

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: oven-sh/setup-bun@v2

      - run: bun install --frozen-lockfile

      - name: Publish packages
        id: changesets
        uses: changesets/action@v1
        with:
          version: bun run version
          publish: bun run release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_CONFIG_PROVENANCE: "true"

      - name: Request docs source pin update
        if: steps.changesets.outputs.published == 'true'
        env:
          DOCS_DISPATCH_TOKEN: ${{ secrets.DOCS_DISPATCH_TOKEN }}
          DOCS_REPOSITORY: ${{ vars.DOCS_REPOSITORY }}
          PACKAGE_NAME: ${{ vars.DOCS_PACKAGE_NAME }}
          PUBLISHED_PACKAGES: ${{ steps.changesets.outputs.publishedPackages }}
        run: |
          # Set DOCS_PACKAGE_NAME to the published package whose release drives the docs pin.
          VERSION=$(printf '%s\n' "$PUBLISHED_PACKAGES" | jq -r --arg name "$PACKAGE_NAME" '.[] | select(.name == $name) | .version // empty')

          if [ -z "$VERSION" ]; then
            echo "No published version found for '$PACKAGE_NAME'; skipping docs pin dispatch."
            exit 0
          fi

          jq -n \
            --arg repo "$GITHUB_REPOSITORY" \
            --arg sha "$GITHUB_SHA" \
            --arg version "$VERSION" \
            '{ event_type: "docs-source-released", client_payload: { repo: $repo, sha: $sha, version: $version } }' > dispatch.json

          curl -fsSL \
            -X POST \
            -H "Accept: application/vnd.github+json" \
            -H "Authorization: Bearer $DOCS_DISPATCH_TOKEN" \
            -H "X-GitHub-Api-Version: 2022-11-28" \
            "https://api.github.com/repos/$DOCS_REPOSITORY/dispatches" \
            --data @dispatch.json

Store:

• DOCS_DISPATCH_TOKEN as a secret in the source repo.
• DOCS_REPOSITORY as a repo variable, for example acme/docs.
• DOCS_PACKAGE_NAME as a repo variable set to the published package that drives docs pins, for example @acme/sdk.

Docs repo PR workflow

The docs UI repo receives the event, updates the remote collection ref on a branch, and opens a PR. Your hosting provider can build PR previews from the docs UI repo as usual.

name: Update docs source pin

on:
  repository_dispatch:
    types:
      - docs-source-released

permissions:
  contents: write
  pull-requests: write

jobs:
  update-source-pin:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Update remote collection pin
        env:
          SOURCE_REPO: ${{ github.event.client_payload.repo }}
          SOURCE_SHA: ${{ github.event.client_payload.sha }}
          SOURCE_VERSION: ${{ github.event.client_payload.version }}
        run: |
          node ./scripts/update-leadtype-source.mjs

      - name: Open pin PR
        uses: peter-evans/create-pull-request@v7
        with:
          branch: docs/source-${{ github.event.client_payload.version }}
          commit-message: Update docs source to ${{ github.event.client_payload.version }}
          title: Update docs source to ${{ github.event.client_payload.version }}
          body: |
            Updates the Leadtype source pin.

            - Source: `${{ github.event.client_payload.repo }}`
            - Commit: `${{ github.event.client_payload.sha }}`
            - Version: `${{ github.event.client_payload.version }}`

By default peter-evans/create-pull-request opens the PR with the workflow's GITHUB_TOKEN, and PRs created that way do not trigger downstream push or pull_request workflows on the docs repo. Hosting-provider previews (Vercel, Cloudflare Pages, Netlify) still build because they run through their own GitHub Apps, but workflow-driven CI on the pin PR — link checks, MDX lint, leadtype lint — silently will not run. If you need those, pass a fine-grained PAT or GitHub App token via the action's token: input.

Keep scripts/update-leadtype-source.mjs in the docs UI repo so the repo owns how its Leadtype config is edited. Prefer a small AST-aware script or a deliberately marked config block over ad hoc shell replacement. If you also pin the released package dependency, update package.json and the lockfile before Open pin PR.

Deployment options

Preview builds

For PR previews, do not update the production pin. Either:

• Let the docs UI repo build previews from source branches by passing a temporary SHA to preview-only CI.
• Dispatch preview events from same-repo PRs only, and require a maintainer-triggered workflow for fork previews.

Keep preview refs separate from the production remote collection ref.

Agent prompt

You are setting up a multi-repo Leadtype docs pipeline.
Requirements:

The package/source repo owns MDX and releases packages.
The docs UI repo owns the rendered site.
Production docs must be pinned to an explicit released source revision, not the source repo default branch.
Configure leadtype.config.ts in the docs UI repo with a remote Leadtype collection whose repository points at the source repo, whose ref is pinned to the released commit SHA, and whose sourceConfig is true.
Keep source-owned navigation, legacy groups, frontmatterSchema, flatteners, and mounts in the source repo's docs/docs.config.ts.
Keep the package version near that config when useful for reviewers, PR titles, dependency pins, or release dashboards.
Run leadtype generate --sync before the docs UI framework build. Use --offline only when the cache is already present.
Prefer manual pin PRs as the baseline. If automating, make the source repo dispatch a small payload after publish and make the docs UI repo open a PR that updates the remote collection ref.
Do not make package publish directly deploy production docs unless the project explicitly wants that coupling.
For PR previews, do not update the production pin. Keep preview refs separate.
Return the changed workflows, the remote collection shape, required secrets and variables, and the build scripts needed for the docs UI repo.

What to read next