@textmode/docs

Shared documentation generation and validation for public textmode.js libraries. The package owns the TypeDoc stack, Markdown plugins, public API checks, example validation, and API-link maintenance behind one command.

Ownership

• package.json owns the package name, description, and TypeScript dependency.
• textmode.docs.config.mjs owns project-specific documentation policy.
• @textmode/docs owns TypeDoc and its plugins, shared defaults, rendering, validation, link editing, and command behavior.

Consumers should not define package.json#typedocOptions, maintain another tooling config, invoke TypeDoc directly, or import package internals.

Installation

npm install --save-dev @textmode/docs typescript

Configuration

Conventional projects need no configuration file. Create textmode.docs.config.mjs at the project root only for policy that differs from the shared defaults:

import { defineDocs } from '@textmode/docs';

export default defineDocs({
	entryPoints: ['src/index.ts'],
	linkEntryPoints: [
		{
			path: 'src/index.ts',
			tsconfig: 'tsconfig.json',
			namespaceExportsOnly: false,
		},
	],
	sourceRoots: ['src'],
	outputDir: 'api/example-package',
	apiBaseUrl: 'https://code.textmode.art/api/example-package',
	tsconfig: 'tsconfig.json',
	memberPageKinds: ['method', 'property', 'accessor'],
	stripApiSelfLinks: 'full',
	checks: {
		apiLinks: ['class', 'interface', 'typeAlias', 'enum', 'variable', 'function', 'method', 'accessor', 'property'],
		docstrings: [
			'class',
			'interface',
			'typeAlias',
			'enum',
			'variable',
			'function',
			'method',
			'accessor',
			'property',
		],
		examples: ['function', 'method', 'accessor'],
	},
	examples: {
		forbidGallerySourceBase: true,
	},
	typedoc: {},
});

Paths resolve relative to the project root containing package.json.

Supported reflection names are class, interface, typeAlias, enum, variable, function, method, accessor, and property. Set examples: false to disable gallery, manifest, and sketch checks for a package without examples.

The typedoc object can override registered TypeDoc options except entryPoints, out, tsconfig, plugin, router, emit, watch, treatWarningsAsErrors, treatValidationWarningsAsErrors, and options whose names begin with textmode.

editLink: true enables the "Edit this page on GitHub" link on generated API pages for the package. The default (false) omits the link because API reference is generated and should not be edited in place via the docs site.

Defaults

| Setting | Default | | ------------------------------ | ----------------------------------------------------- | | Package name and description | package.json | | Entrypoint and link entrypoint | src/index.ts | | Source roots | Derived from link entrypoints | | TypeScript config | tsconfig.json | | Output | api/<package-name> | | Hosted API URL | https://code.textmode.art/api/<package-name> | | Member pages | Methods, properties, and accessors | | Self-link stripping | full | | Edit link on API pages | Disabled (opt in per package with editLink: true) | | Sorting | Kind, instance-first, alphabetical (except documents) | | API-link kinds | All supported reflection kinds | | Required docstrings | All supported reflection kinds | | Required examples | Functions, methods, and accessors | | Example checks | Gallery, manifest, and sketch checks enabled | | Gallery source bases | Hardcoded source bases rejected |

Configuration precedence is shared defaults, derived package metadata, textmode.docs.config.mjs, then command-owned overrides such as --out, strict checking, and watch mode. Use --show-config to inspect the effective values and the origin of every setting.

The shared sorting policy groups API reflections by kind, lists instance members before static members, and alphabetizes non-document reflections. A project can override it with typedoc.sort when its API needs a different presentation.

Commands

textmode-docs check
textmode-docs build [--out <directory>]
textmode-docs watch [--out <directory>]
textmode-docs links add
textmode-docs api-check [--include-accessors]

• check renders to fresh temporary storage, treats TypeDoc and validation warnings as errors, validates routes, public API documentation, links, and enabled example policies, then removes the temporary output.
• build cleans and renders the configured output directory.
• watch performs an initial render and rebuilds through TypeDoc's watcher.
• links add derives current routes in temporary storage and idempotently inserts or updates JSDoc API links inside sourceRoots.
• api-check runs only public API documentation policy. --include-accessors adds accessors to policies that normally omit them.

Every command accepts --cwd, --config, --show-config, --help, and --version. build and watch also accept --out. Unknown commands, flags, missing values, and extra positional arguments are rejected.

Normal results are written to stdout and diagnostics to stderr. Exit status 0 means success, 1 means documentation or content validation failed, and 2 means invocation, configuration, dependency, input, or internal-tool failure.