Skip to content

Latest commit

 

History

History
1062 lines (750 loc) · 32.8 KB

specification.md

File metadata and controls

1062 lines (750 loc) · 32.8 KB

Specification

Version: 1.0.1

Authored By: Aviv Keller (me@aviv.sh)

This document specifies the Markdown format consumed by @doc-kit/core. It defines the structural, syntactic, and semantic rules that documents MUST follow to be correctly parsed. The format is a strict superset of GitHub Flavored Markdown (which itself is a strict superset of CommonMark), adding conventions for API metadata, type annotations, stability indicators, and structured parameter lists.

Because this format is a superset, all constructs valid in GFM remain valid here. This specification only defines the additional constraints and semantics layered on top. Where a GFM construct is given special meaning by this specification (e.g., blockquotes as stability indicators, unordered lists as typed parameter lists), that special meaning is documented in the relevant section.


1. Terminology and Conventions

1.1. Requirement Level Keywords

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in ALL CAPITALS, as shown here.

1.2. Definitions

The following terms are used throughout this specification with the meanings given below.

Document. A single Markdown source file conforming to this specification. Each document describes one API module, one conceptual topic, or one index listing.

Entry. A discrete API element within a document. An entry begins at a heading and extends to the next heading of equal or lesser depth, or to the end of the file. An entry comprises a heading, optional YAML metadata, optional stability indicator, optional typed parameter list, and a prose body.

Section. A contiguous range of entries sharing a common parent heading.

Typed list. An unordered list whose items follow the typed parameter syntax defined in §9. Typed lists provide structured type, default-value, and description metadata for function parameters, return values, or object properties.

Stability indicator. A blockquote element whose text content begins with Stability: followed by a numeric level, indicating the API lifecycle stage of the enclosing entry. See §7.

YAML metadata block. An HTML comment whose content begins with the keyword YAML and contains YAML 1.2 data providing version-history and classification metadata for the enclosing entry. See §6.

Simple directive. An HTML comment whose content follows the compact key=value pattern, providing document-level or section-level metadata. See §6.2.

Type annotation. A TypeScript type expression enclosed in balanced {curly braces} within a typed list item, or in prose. It is rendered as a single code fragment whose type names are resolved to hyperlinks. See §8.


2. Conformance

2.1. Base Grammar

A conforming document MUST be valid GitHub Flavored Markdown (GFM), which is itself a superset of CommonMark. This specification is a strict superset of GFM: all GFM constructs are valid, and this specification layers additional structure and semantics on top.

Where this specification assigns special meaning to a GFM construct (for example, blockquotes used as stability indicators, or unordered lists used as typed parameter lists), that special meaning is defined in the relevant section. All other GFM constructs retain their standard behavior.

2.2. Character Encoding

Documents MUST be encoded in UTF-8. A byte order mark (BOM) MUST NOT be present.

2.3. Line Endings

Documents SHOULD use LF (U+000A) line endings. Both LF and CRLF (U+000D U+000A) MUST be accepted by a conforming implementation. Documents MUST end with a trailing newline.

2.4. Whitespace

Indentation MUST use spaces. Tab characters (U+0009) MUST NOT appear in document source except within fenced code block content, where they reproduce literal output.


3. Document Structure

3.1. Top-Level Ordering

A conforming document MUST contain elements in the following order. Items marked OPTIONAL MAY be omitted entirely.

  1. Title heading (OPTIONAL, RECOMMENDED) - An ATX heading at depth 1.
  2. Simple directives (OPTIONAL) - Zero or more HTML comment directives providing document-level metadata. These MUST immediately follow the title heading.
  3. Module-level stability indicator (OPTIONAL) - A stability blockquote applying to the document as a whole.
  4. Introductory prose (OPTIONAL) - Free-form Markdown content.
  5. API entry sections (OPTIONAL, REPEATABLE) - One or more headings at depth 2 or greater, each introducing an entry. Each entry follows the sub-ordering in §3.2.
  6. Link reference definitions (OPTIONAL) - Collected at the end of the file, after all entry sections.
# Command-line API

<!--introduced_in=v5.9.1-->

<!--type=misc-->

Node.js comes with a variety of CLI options. These options expose built-in
debugging, multiple ways to execute scripts, and other helpful runtime options.

3.2. Entry Ordering

Within each API entry, elements MUST appear in this order:

  1. Heading (REQUIRED) - An ATX heading.
  2. YAML metadata block (OPTIONAL) - Immediately following the heading, with no intervening content.
  3. Stability indicator (OPTIONAL) - A stability blockquote.
  4. Typed parameter list (OPTIONAL) - An unordered list describing parameters, return value, type, or extends clause.
  5. Prose body (OPTIONAL) - Free-form Markdown content.
  6. Code examples (OPTIONAL) - Fenced code blocks.
  7. Sub-entries (OPTIONAL, REPEATABLE) - Deeper headings beginning nested entries, following this same ordering recursively.

4. Headings

4.1. Style

All headings MUST use ATX style (# prefix). Setext-style headings (underline with = or -) MUST NOT be used.

4.2. Depth Semantics

4.2.1. Depth 1

The document title. Exactly one depth-1 heading SHOULD appear per document.

4.2.2. Depth 2

Top-level API entries: classes, module-level functions, module-level properties, module-level events, and major conceptual sections.

4.2.3. Additional Depths

Nested API entries: instance methods, instance properties, class events, constructors, static methods, sub-properties, and further nesting. Static methods SHOULD appear at one depth below their class heading.

Documents SHOULD NOT use heading depths greater than 5.

4.3. Entry Type Classification

Each heading is classified into an entry type by testing its text against the patterns below, evaluated in the order given. The first match wins. All pattern matching is performed on the plain text of the heading after stripping the ATX prefix.

4.3.1. Method

The heading text is a backtick-wrapped expression containing a dotted or bracketed receiver, a member accessor, and parentheses. The parentheses distinguish methods from properties.

### `fs.readFile(path[, options], callback)`
### `buf.write(string[, offset[, length]][, encoding])`
### `request[Symbol.asyncIterator]()`

4.3.2. Event

The heading text begins with the literal prefix Event: followed by optional whitespace and a backtick-wrapped, single-quoted event name.

### Event: `'close'`
### Event: `'data'`

4.3.3. Class

The heading text begins with the literal prefix Class: followed by optional whitespace and a backtick-wrapped class identifier. The class name SHOULD begin with an uppercase ASCII letter.

## Class: `http.Server`
## Class: `EventEmitterAsyncResource`

4.3.4. Constructor

The heading text is a backtick-wrapped expression beginning with the keyword new, followed by whitespace, then an uppercase-initial class identifier and parenthesized parameters.

### `new Agent([options])`
### `new Buffer(size)`

4.3.5. Static Method

The heading text begins with the literal prefix Static method: followed by optional whitespace and a backtick-wrapped qualified method call (with parentheses).

#### Static method: `Buffer.alloc(size[, fill[, encoding]])`
#### Static method: `Buffer.from(string[, encoding])`

4.3.6. Property

The heading text is a backtick-wrapped dotted or bracketed property access that does not contain parentheses. The absence of parentheses distinguishes properties from methods.

### `buf.length`
### `os.EOL`
### `http.METHODS`

4.3.7. Default Classification

If no pattern matches, the entry is classified as a miscellaneous section.

4.4. Document Type and Heading Interpretation

The document-level type directive determines how classified entries are interpreted with respect to module membership and export scope. The type establishes a default context for all headings in the file. This context can be overridden at the section level or at the individual entry level.

4.4.1. Module Documents

When type is module (or when no type directive is present, as module is the default), classified entries are treated as exports of the module identified by the document's filename or module simple directive.

A single module document MAY describe exports from more than one related module (e.g., fs and fs/promises). The module boundary does not affect entry classification or rendering; the classification algorithm in §4.3 operates identically regardless of which module an entry belongs to. Where the distinction does matter (e.g., for import paths or module-specific rendering), a module context override SHOULD be used.

# File system

<!--type=module-->
<!--name=fs-->

4.4.2. Miscellaneous Documents

When type is misc, headings are not assumed to be module exports. Classified entries are treated as conceptual sections or standalone topics.

# C++ addons

<!--type=misc-->

4.4.3. Global Documents

When type is global, classified entries are treated as global APIs, available without an import or require. Implementations MAY render global entries differently from module exports (e.g., omitting a module prefix).

# Global objects

<!--type=global-->

4.4.4. Module Context Override

The module simple directive overrides the owning module for all sub-entries beneath the heading it is attached to. This allows a single document to describe exports from multiple modules without splitting into separate files.

## Promises API

<!--module=node:fs/promises-->

### `fsPromises.readFile(path[, options])`

All headings beneath the annotated heading inherit the overridden module context until the next heading of equal or lesser depth, or until another module directive.

4.4.5. Per-Entry Override

Individual entries MAY override their classification context using the type field in a YAML metadata block:

### `globalThis.structuredClone(value[, options])`

<!-- YAML
added: v17.0.0
type: global
-->

This is useful in module-type documents that contain isolated global entries, or in misc-type documents that contain isolated module exports.

4.5. Heading Text Conventions

4.5.1. Code Spans in Headings

Programmatic identifiers (method names, property names, class names, event names, flag names) MUST be wrapped in backtick code spans. Prose section headings (e.g., ## Synopsis) MUST NOT use backticks.

4.5.2. Event Name Quoting

Event names SHOULD be wrapped in single quotes inside the backticks:

### Event: `'drain'`

4.5.3. Multiple Forms

When a single API entry has multiple invocation forms (e.g., short and long flag names), they SHOULD be listed in a single heading separated by , :

### `-c`, `--check`

5. Signature Syntax

Method and constructor headings encode their call signature directly in the heading text.

5.1. Required Parameters

Required parameters appear as bare identifiers inside the parentheses:

### `fs.readFile(path, callback)`

5.2. Optional Parameters

Optional parameters are wrapped in square brackets:

### `fs.readFile(path[, options], callback)`

5.3. Nested Optionals

Parameters that are only meaningful when a preceding optional parameter is provided use nested brackets:

### `buf.write(string[, offset[, length]][, encoding])`

5.4. Rest Parameters

Rest parameters use ellipsis notation within square brackets:

### `path.join([...paths])`

5.5. Constraints

Default values MUST NOT appear in the heading signature. Defaults are documented in the typed parameter list using the **Default:** pattern.

Type annotations MUST NOT appear in the heading signature. Types are documented in the typed parameter list.


6. YAML Comment Blocks

6.1. Block Syntax

YAML metadata is embedded in HTML comments. The opening delimiter is <!-- YAML (with at least one space before YAML) and the closing delimiter is -->. The content between these delimiters MUST be valid YAML 1.2.

<!-- YAML
added: v12.0.0
-->

The comment MUST appear on its own lines. A heading MAY contain multiple YAML metadata blocks and related HTML comments within its subtree; such blocks MUST be merged into a single metadata object for that heading.

6.2. Simple Directives

Document-level and section-level metadata uses a compact key=value syntax inside HTML comments. Each directive has the form <!--key=value-->.

Document-level directives (i.e. introduced_in) SHOULD appear immediately after the depth-1 heading. Section-level directives (see §6.2.5) SHOULD appear immediately after the heading they annotate.

# File System

<!--introduced_in=v0.10.0-->
<!--type=module-->
<!--name=fs-->
<!--source_link=lib/fs.js-->

Each directive occupies exactly one HTML comment. The following keys are defined:

6.2.1. introduced_in

A version string indicating when the module was introduced.

6.2.2. type

The document classification. Recognized values are module, misc, and global. Implementations MAY define additional values. If no type directive is present, the default is module.

See §4.4 for how document type influences heading interpretation.

6.2.3. source_link

A relative file path to the implementation source. Rendered as a link.

6.2.4. llm_description

A plain-text description optimized for consumption by Large Language Models, used in preference to extracted prose where available.

6.2.5. module

Overrides the owning module for all sub-entries beneath the annotated heading. The value is a module specifier (e.g., node:fs/promises). This directive is placed immediately after a heading, not after the depth-1 heading.

See §4.4.4 for full semantics.

## Promises API

<!--module=node:fs/promises-->

6.3. YAML Metadata Fields

The following fields are defined within YAML metadata blocks. Any field not listed here is reserved for future specification and MUST be ignored by conforming implementations that do not recognize it.

6.3.1. added

The version(s) in which this entry was first available.

  • Type: version string, or array of version strings for backports.
  • Example: added: v8.0.0

When an API was backported, the array MUST list versions in descending order.

6.3.2. deprecated

The version(s) in which this API was deprecated.

  • Type: version string, or array of version strings.
  • Example: deprecated: v6.0.0

6.3.3. removed

The version(s) in which this API was removed.

  • Type: version string, or array of version strings.
  • Example: removed: v14.0.0

6.3.4. changes

A chronological array of change records. Each record MUST contain the following properties:

  • version (REQUIRED) - A version string or array of version strings.
  • pr-url (REQUIRED) - A full URL to the pull request.
  • description (REQUIRED) - A human-readable description. Inline Markdown is permitted. Multi-line descriptions use YAML block-scalar indentation.
changes:
  - version: v18.0.0
    pr-url: https://github.com/nodejs/node/pull/41678
    description: Passing an invalid callback now throws
      `ERR_INVALID_ARG_TYPE`.
  - version:
      - v21.7.0
      - v20.12.0
    pr-url: https://github.com/nodejs/node/pull/51289
    description: Added multi-line value support.

6.3.5. type (Override)

When present in a YAML block, this overrides the heading classification type for the enclosing entry. It can also override the document-level export/global context as described in §4.4.5.

  • Type: string (one of the type names defined in §4.3, or a context value such as global).
  • Example: type: method

6.3.6. source_link

Relative path to the implementation source file. Identical semantics to the simple directive of the same name.

6.3.7. llm_description

Identical semantics to the simple directive of the same name.

6.4. Version Strings

Version strings MUST follow semantic versioning with a lowercase v prefix, in the form v<MAJOR>.<MINOR>.<PATCH>. Implementations MAY define additional sentinel values for unreleased features (e.g., placeholder strings that are replaced during a release process).

6.5. Plain Tag Comments

HTML comments that do not match the YAML block pattern and do not match the simple directive pattern are parsed as tags. If the content is a simple string, it is stored as a tag on the entry:

<!-- legacy -->

Implementations MAY define reserved tag values for special purposes such as content slot markers.

6.6. Frontmatter Conversion

Standard YAML frontmatter delimited by --- at the start of a file is converted to a YAML comment block during preprocessing. The following two forms are equivalent:

---
introduced_in: v0.10.0
---
<!-- YAML
introduced_in: v0.10.0
-->

Documents SHOULD use the HTML comment syntax directly. Frontmatter is accepted for compatibility.

6.7. Placement

A YAML metadata block SHOULD immediately follow the heading it annotates. This placement is RECOMMENDED for clarity and consistency, but the parser accepts YAML blocks anywhere within the annotated entry's subtree.


7. Stability Indicators

7.1. Syntax

A stability indicator is a blockquote whose first paragraph begins with Stability: followed by a numeric level, a dash separator (-), and a textual label. The level is an integer or a decimal sub-level. The description extends to the end of the blockquote.

> Stability: 2 - Stable

7.2. Levels

Four stability levels are defined.

7.2.1. Level 0 - Deprecated

The feature may emit warnings. Backward compatibility is not guaranteed.

7.2.2. Level 1 - Experimental

Not subject to semantic versioning rules. Non-backward-compatible changes or removal may occur in any future release.

7.2.3. Level 2 - Stable

Compatibility with the ecosystem is a high priority.

7.2.4. Level 3 - Legacy

Still covered by semantic versioning guarantees, but no longer actively maintained. Other alternatives are available.

7.3. Sub-Levels

Level 1 supports decimal sub-levels indicating maturity within the experimental phase. This specification only defines semantics for decimal sub-levels of level 1.

7.3.1. 1.0 - Early Development

Unfinished and subject to substantial change.

7.3.2. 1.1 - Active Development

Nearing minimum viability.

7.3.3. 1.2 - Release Candidate

Expected to become stable.

7.4. Multi-Line Indicators

The description MAY continue on subsequent blockquote lines:

> Stability: 1 - Experimental. This API is under active development and
> may change without notice between minor releases.

7.5. Inline Content

The description MAY contain inline Markdown such as links and code spans:

> Stability: 3 - Legacy: Use [`alternative()`][] instead.

7.6. Placement

A stability indicator MUST appear after the YAML metadata block (if present) and before the typed parameter list and prose body. A document SHOULD have at most one stability indicator per entry:

### `myModule.myMethod()`

<!-- YAML
added: v1.2.3
-->

> Stability: 3 - Legacy: Use [`alternative()`][] instead.

A stability indicator on the depth-1 heading applies to the document as a whole.


8. Type Annotations

8.1. Syntax

A type annotation is any balanced {curly brace} span in text. The content between the braces is a TypeScript type expression — anything valid on the right-hand side of a TypeScript type X = ... alias.

Annotations appear both in typed parameter lists (as part of item structure) and in prose text (as inline references); both forms are parsed and rendered identically.

8.2. Parsing

Implementations MUST parse each annotation whose value is not a whole-value map match under the TypeScript type grammar. Implementations SHOULD collect every annotation in a document and parse them in a single batch.

An annotation that fails to parse MUST produce a warning identifying the source location, and MUST be rendered as plain, unlinked code.

8.3. Resolution

Each annotation resolves to a set of hyperlinks:

  1. Whole-value lookup. If the entire annotation value matches a type-map entry verbatim, the whole annotation becomes a single link. This permits display-name keys that are not valid TypeScript identifiers (e.g. zlib options).
  2. Identifier resolution. Otherwise, every type name in the parsed expression resolves individually: keyword types (string, number, boolean, ...), type-reference names, qualified names (vm.Module), typeof targets, and import('mod').X qualifiers. Structural names — function parameter names, object property keys — are never resolved.

Each name resolves through the following tiers; the first match wins:

  1. The configurable type map provided to the toolchain, which associates names with documentation URLs. An example type map is available for viewing here.
  2. JavaScript primitives and built-in (TC39) globals, matched case-insensitively: string, number, boolean, bigint, symbol, null, undefined, integer, Array, Object, Function, Promise, and others.
  3. Web platform APIs documented on MDN, matched case-insensitively.
  4. Dotted-name heuristic: names containing . are split on the first . to derive a module name and member identifier, producing a cross-document link of the form <module>.md#<identifier>.

A name that no tier resolves stays plain — this is not an error.

8.4. Rendering

The whole annotation renders as ONE inline code fragment. Each resolved name becomes a hyperlink spanning exactly its character range within the fragment; unresolved names remain plain text inside it. Implementations MAY syntax-highlight the fragment as TypeScript.


9. Typed Parameter Lists

A typed list is an unordered Markdown list used to define parameters, properties, or other lists of types.

9.1. Identification

A typed list is an unordered Markdown list recognized by the content of its first item. A list is a typed list if its first item matches any of these conditions:

  1. It begins with text matching one of the special prefixes (Returns:, Extends:, Type:).
  2. It begins with a type annotation.
  3. It begins with an inline code span (the parameter name) followed by a space and then a type annotation.

9.2. Item Structure

Each item in a typed list has the form:

* `name` {Type} Description text. **Default:** `value`.

The components, in order, are:

  1. Bullet marker - *, +, or -.
  2. Parameter name - A backtick code span. REQUIRED for parameter items; absent for Returns:, Type:, and Extends: items.
  3. Type annotation - A single {...} TypeScript type expression (a union belongs inside it, e.g. {string|Buffer}). OPTIONAL.
  4. Description - Free-form prose. OPTIONAL.
  5. Default value - The exact pattern **Default:** \value``. OPTIONAL.

9.3. Special Prefixes

9.3.1. Returns:

Denotes the return value of a function:

* Returns: {Promise} The file contents.

9.3.2. Extends:

Denotes the superclass of a class:

* Extends: {EventEmitter}

Extends: items SHOULD appear as the first item in a class entry's typed list.

9.3.3. Type:

Denotes the type of a property or constant:

* Type: {string}

9.4. Nested Properties

Object parameters document their properties using indented sub-lists:

* `options` {Object}
  * `encoding` {string} Character encoding. **Default:** `'utf8'`.
  * `flag` {string} File system flag. **Default:** `'r'`.
  * `signal` {AbortSignal} Abort signal.

Nesting MAY continue to arbitrary depth.

9.5. Default Values

Optionality is indicated by the **Default:** pattern. Parameters with a documented default are considered optional. The default value MUST be wrapped in a backtick code span:

* `encoding` {string} **Default:** `'utf8'`.

9.6. Placement

A typed list MUST appear after the stability indicator (if present) and before the prose body. When present, the list is extracted from the content flow and represented as structured data in output.


10. Code Blocks

10.1. Fence Style

Code blocks MUST use fenced syntax (triple backticks). Indented code blocks MUST NOT be used.

10.2. Info Strings

Every fenced code block SHOULD include a language identifier in its info string. The language identifier is the first whitespace-delimited token after the opening fence.

Common language identifiers include: js, cjs, mjs, json, console, bash, text, typescript, c, cpp, http, markdown, diff.

10.3. The displayName Attribute

A fenced code block MAY include a displayName key-value attribute after the language identifier in the info string. The displayName provides a human-readable label for the code block, used in rendered output. The attribute syntax is displayName="value" where the value is a double-quoted string.

Implementations MAY support additional info string attributes using the same key="value" syntax.

```js displayName="Reading a file"
const data = fs.readFileSync('/path/to/file');
```

11. Links and Cross-References

11.1. Reference-Style Links

All links SHOULD use collapsed reference-style links:

See [`fs.readFile()`][] for details.

with corresponding link reference definitions at the end of the document.

11.2. Cross-Document Links

Links to other documents in the same documentation set MUST use relative paths with .md extensions in the source. Conforming implementations MUST rewrite the .md extension to the appropriate output extension (e.g., .html) during generation:

[Stream documentation]: stream.md#class-streamreadable

11.3. External Links

External links MUST use full URLs including the protocol:

[MDN Web Docs]: https://developer.mozilla.org/

11.4. System-Call Auto-Linking

References to system calls in the format name(section) (e.g., open(2) links to https://man7.org/linux/man-pages/man2/open.2.html) are automatically converted to links to the appropriate manual page documentation by conforming implementations.

11.5. Type Auto-Linking

Type annotations in prose text (§8.1) are parsed (§8.2), resolved (§8.3), and rendered (§8.4) exactly like annotations in typed parameter lists.

11.6. Link Reference Definitions

Link reference definitions SHOULD be collected at the end of the document, after all content sections:

[`fs.readFile()`]: #fsreadfilepath-options-callback
[`stream.Readable`]: stream.md#class-streamreadable