Diagnostics

Structured, source-located problems instead of silence.

When Blasdoc cannot do something, it says so — with a code, a message and a position in the source. It does not guess, and it does not fail silently.

Reading them

From a page:

import { blasdocPageDiagnostics } from '@blasdoc/angular';
 
const problems = blasdocPageDiagnostics(page);

From <blasdoc-content>:

html

<blasdoc-content [source]="markdown" (diagnostics)="onProblems($event)" />

The shape

interface BlasdocDiagnostic {
  readonly code: string;        // BLASDOC_*
  readonly severity: 'error' | 'warning';
  readonly message: string;
  readonly position?: BlasdocPosition;
}

The codes

Code	When
`BLASDOC_UNKNOWN_COMPONENT`	a tag names a component that is not registered, or a loader returned nothing
`BLASDOC_EXPRESSION_FAILED`	an expression could not be parsed or evaluated
`BLASDOC_TWO_WAY_WITHOUT_OUTPUT`	`[(x)]` on a component with no `xChange` output
`BLASDOC_UNKNOWN_THEME`	a fence or document selected an unregistered theme
`BLASDOC_UNKNOWN_LANGUAGE`	a fence named a language Shiki does not have
`BLASDOC_HIGHLIGHT_FAILED`	highlighting threw; the block renders unhighlighted
`BLASDOC_HTML_NOT_ALLOWED`	a tag or attribute the HTML policy removed

Late diagnostics

Highlighting and lazy components resolve after the render pass returns, so their problems arrive late. They are reported through the same channel — a diagnostics panel that reads once at render time will miss them, so read on change.

In practice

The best use of diagnostics is a test. This site asserts that every page reports none, which is what keeps its examples honest: a page that documented a feature Blasdoc lacks would fail the suite rather than quietly render nothing.

for (const page of DOC_PAGES) {
  const view = await open(`/docs/${page.slug}`);
  expect(view.diagnostics()).toEqual([]);
}