@beblurt/dblurt

Appearance

Maintainer workflows ​

This page records maintainer-facing documentation workflows. It may mention documentation tooling because it is not part of the first-time developer learning path.

Local validation ​

Use the full local check before asking for maintainer review:

bash
npm run docs:check
npm run docs:public:build
npm run typecheck
npm run lint

npm run docs:check validates:

  • Markdown links and fenced-code balance across source docs, site pages, AI context and example catalog pages;
  • AI-layer hygiene;
  • preferred public example style: TypeScript + ESM by default, CommonJS only on explicit compatibility pages;
  • generated /api/ links include target="_self" so VitePress does not intercept TypeDoc HTML navigation;
  • example metadata and catalog entries;
  • stale-sensitive documentation claims against package metadata;
  • executable read-only/static Node examples;
  • TypeScript example compilation;
  • TypeDoc warning baseline;
  • VitePress site build.

CI validation ​

CI should avoid live public RPC dependency by using:

bash
npm run docs:check:ci

That command sets DBLURT_DOCS_CHECK_SKIP_LIVE_EXAMPLES=1 and still validates metadata, TypeScript compilation, TypeDoc warnings and the site build.

Public site build ​

Build the GitLab Pages artifact locally with:

bash
npm run docs:public:build

This creates an ignored public/ directory:

text
public/       human documentation site
public/api/   generated API reference

Do not edit public/ by hand. Regenerate it from source pages and TypeScript source.

GitLab Pages ​

.gitlab-ci.yml defines:

  • docs:check in the validate stage;
  • pages in the deploy stage, restricted to the default branch;
  • public/ as the GitLab Pages artifact.

The Pages job publishes the current documentation site root and the API reference under /api/.

TypeDoc warning baseline ​

npm run docs:check treats the current five TypeDoc warnings as an explicit baseline. New warning classes fail the check.

The current warnings are about internal/public-boundary types referenced by public options or helpers:

  • BroadcastAPI referenced by Client.broadcast;
  • CoreClientLike and CoreModuleLike referenced by core transport options;
  • CoreClientLike and CoreModuleLike referenced by experimental client options.

Do not silence these warnings just to make reports green. Either expose/reshape the public surface intentionally or keep the baseline until the maintainer approves an API-surface change.