How to add an external documentation source

Add a repository's Markdown documentation to the EOS docs site by registering it as an external source. The docs app fetches the content at build time and renders it alongside local documentation with full-text search and sidebar navigation.

Prerequisites

A GitHub fine-grained Personal Access Token with read-only Contents access on the target repository.
The target repository contains Markdown files in a known subdirectory.

Register the source

Add an entry to apps/docs/external-docs.json:

json

{
  "sources": [
    {
      "prefix": "my-service",
      "owner": "MyOrg",
      "repo": "my-service",
      "ref": "main",
      "docspath": "docs",
      "label": "My Service"
    }
  ]
}

Field	Required	Description
`prefix`	Yes	URL path prefix and collection identifier
`owner`	Yes	GitHub organisation or user that owns the repository
`repo`	Yes	Repository name
`ref`	Yes	Branch, tag, or commit SHA to fetch
`docspath`	Yes	Subdirectory containing the Markdown files
`label`	No	Human-readable name shown in sidebar navigation

Set the GitHub token

The build requires the EOS_DOCS_GH_TOKEN environment variable. Set it in each environment that runs the docs build.

Local development — create apps/docs/.env (already gitignored):

sh

EOS_DOCS_GH_TOKEN=github_pat_...

CI — add the token as a repository secret and reference it in the workflow:

yaml

env:
  EOS_DOCS_GH_TOKEN: ${{ secrets.EOS_DOCS_GH_TOKEN }}

Cloudflare Pages — add EOS_DOCS_GH_TOKEN as an environment variable in the project settings for both Production and Preview environments.

!WARNING When EOS_DOCS_GH_TOKEN is absent the build completes successfully but silently skips all external sources. No error is raised. Verify the token is set if external content is missing from the built site.

Link behaviour in external docs

The docs app rewrites links in external collection files according to these rules:

Markdown links (e.g. quickstart.md, ./guides/setup.md) resolve to pages within the docs site, relative to the current file's position in the collection.
Non-markdown relative links (e.g. app/Models/Order.php, schema.json) resolve to GitHub blob URLs, relative to the file's directory within the collection (not the repository root).
Absolute URLs and leading-slash paths are left unchanged.
Parent traversal (../) is supported. Use it to reference files above the current directory within the repository.

!IMPORTANT Non-markdown links resolve relative to the file's position in the collection, not the repository root. A file at guides/quickstart.md that links to app/Models/Order.php produces a GitHub URL pointing to guides/app/Models/Order.php. To link to the repository root, prefix the path with ../ (e.g. ../app/Models/Order.php).

Verify the build

Run the docs build to confirm the external source is fetched and rendered:

sh

nx run @eos/docs:build

Check that pages from the new source appear under /<prefix>/ in the generated output.