From the repositories

Guides, API references and changelogs that the site publishes straight out of the Gland repositories.

Everything in this section is generated at build time from the documentation that lives in the Gland repositories themselves. Nothing here is written twice: the guide you are reading is the same Markdown file that sits in the repository, and the version on the badge is the one that repository’s package.json declares right now.

Why it is organised this way

A JSDoc block, a guide or a changelog entry is written in the package it documents, because that is where the reader who needs it will look for it, and because that is where it is still correct. The site does not copy it, so it cannot drift.

Concretely:

Step	What happens
Read	A sibling checkout next to this repository wins when one exists, so an edit is published before it is pushed. Otherwise the file is read from `raw.githubusercontent.com` at a pinned commit.
Convert	The document’s own title becomes page front matter, cross-links between mirrored documents become site links, and anything not mirrored becomes a link into the repository.
Generate	Every page under `/reference`, every page under `/changelog`, the sidebar groups, and the version on every package card.
Publish	The result is written into the content collection before Astro starts, so the pages are ordinary Starlight pages by the time the build reads them.

Not generated: the narrative pages — Introduction, Guides, the FAQ — and the pages that describe a decision rather than an API.

Pinning is what makes this trustworthy. Every mirrored page records the exact commit it came from, and its “Edit this page” link opens the upstream file, so a correction is made where the document lives.

Publishing something new

Add an entry to scripts/docs-sync/config.mjs and it is on the site at the next build — no page is created by hand and no sidebar link is added by hand.

1
{
2
  id: 'http',
3
  label: '@glandjs/http',
4
  repo: 'glandjs/http',
5
  ref: 'main',
6
  workspace: 'http',
7
  packages: [{ from: 'packages/http/package.json' }],
8
  docs: [
9
    {
10
      from: 'docs/guides/cors.md',   // where the file is in the repository
11
      route: 'guides/cors',          // where it lands on the site
12
      title: 'CORS',
13
      description: 'One policy, one implementation, five adapters.',
14
      sidebar: { label: 'CORS', group: 'Guides', order: 9 },
15
    },
16
  ],
17
  changelog: { from: 'docs/CHANGELOG.md', changesets: '.changeset' },
18
}

Running the sync yourself

1
pnpm docs:sync          # read sibling checkouts when they exist
2
pnpm docs:sync:remote   # ignore local checkouts, always use GitHub
3
pnpm docs:sync:watch    # re-publish whenever a checkout changes
4
pnpm docs:check         # verify every configured source is readable

dev and build run the sync first, so there is nothing extra to remember. Set GLAND_DOCS_SOURCE=local to require a checkout and fail loudly if one is missing, or GLAND_DOCS_SOURCE=remote to always read from GitHub. GITHUB_TOKEN raises the API rate limit when many repositories are read in one run.

The repositories

Reference	Repository	Packages
`@glandjs/http`	`glandjs/http`	`@glandjs/http` and one adapter per server
`@glandjs/events`	`glandjs/events`	`@glandjs/events`
`@glandjs/emitter`	`glandjs/emitter`	`@glandjs/emitter`
`@glandjs/core`	`glandjs/gland`	`@glandjs/core`, `@glandjs/common`

Changelogs

Page	Source
`@glandjs/http`	`glandjs/http` and `.changeset/`
`@glandjs/events`	`glandjs/events`
`@glandjs/emitter`	`glandjs/emitter`
`@glandjs/core` & `common`	`glandjs/gland` and `.changeset/`