Skip to content

chore(docs): ui improvements #993

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
avivkeller wants to merge 1 commit into
base: main
Choose a base branch
from
Open

chore(docs): ui improvements #993

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 0 additions & 104 deletions docs/specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,110 +19,6 @@ 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.

## Table of Contents

- [1. Terminology and Conventions](#1-terminology-and-conventions)
- [1.1. Requirement Level Keywords](#11-requirement-level-keywords)
- [1.2. Definitions](#12-definitions)
- [2. Conformance](#2-conformance)
- [2.1. Base Grammar](#21-base-grammar)
- [2.2. Character Encoding](#22-character-encoding)
- [2.3. Line Endings](#23-line-endings)
- [2.4. Whitespace](#24-whitespace)
- [3. Document Structure](#3-document-structure)
- [3.1. Top-Level Ordering](#31-top-level-ordering)
- [3.2. Entry Ordering](#32-entry-ordering)
- [4. Headings](#4-headings)
- [4.1. Style](#41-style)
- [4.2. Depth Semantics](#42-depth-semantics)
- [4.2.1. Depth 1](#421-depth-1)
- [4.2.2. Depth 2](#422-depth-2)
- [4.2.3. Additional Depths](#423-additional-depths)
- [4.3. Entry Type Classification](#43-entry-type-classification)
- [4.3.1. Method](#431-method)
- [4.3.2. Event](#432-event)
- [4.3.3. Class](#433-class)
- [4.3.4. Constructor](#434-constructor)
- [4.3.5. Static Method](#435-static-method)
- [4.3.6. Property](#436-property)
- [4.3.7. Default Classification](#437-default-classification)
- [4.4. Document Type and Heading Interpretation](#44-document-type-and-heading-interpretation)
- [4.4.1. Module Documents](#441-module-documents)
- [4.4.2. Miscellaneous Documents](#442-miscellaneous-documents)
- [4.4.3. Global Documents](#443-global-documents)
- [4.4.4. Module Context Override](#444-module-context-override)
- [4.4.5. Per-Entry Override](#445-per-entry-override)
- [4.5. Heading Text Conventions](#45-heading-text-conventions)
- [4.5.1. Code Spans in Headings](#451-code-spans-in-headings)
- [4.5.2. Event Name Quoting](#452-event-name-quoting)
- [4.5.3. Multiple Forms](#453-multiple-forms)
- [5. Signature Syntax](#5-signature-syntax)
- [5.1. Required Parameters](#51-required-parameters)
- [5.2. Optional Parameters](#52-optional-parameters)
- [5.3. Nested Optionals](#53-nested-optionals)
- [5.4. Rest Parameters](#54-rest-parameters)
- [5.5. Constraints](#55-constraints)
- [6. YAML Comment Blocks](#6-yaml-comment-blocks)
- [6.1. Block Syntax](#61-block-syntax)
- [6.2. Simple Directives](#62-simple-directives)
- [6.2.1. `introduced_in`](#621-introduced_in)
- [6.2.2. `type`](#622-type)
- [6.2.3. `source_link`](#623-source_link)
- [6.2.4. `llm_description`](#624-llm_description)
- [6.2.5. `module`](#625-module)
- [6.3. YAML Metadata Fields](#63-yaml-metadata-fields)
- [6.3.1. `added`](#631-added)
- [6.3.2. `deprecated`](#632-deprecated)
- [6.3.3. `removed`](#633-removed)
- [6.3.4. `changes`](#634-changes)
- [6.3.5. `type` (Override)](#635-type-override)
- [6.3.6. `source_link`](#636-source_link)
- [6.3.7. `llm_description`](#637-llm_description)
- [6.4. Version Strings](#64-version-strings)
- [6.5. Plain Tag Comments](#65-plain-tag-comments)
- [6.6. Frontmatter Conversion](#66-frontmatter-conversion)
- [6.7. Placement](#67-placement)
- [7. Stability Indicators](#7-stability-indicators)
- [7.1. Syntax](#71-syntax)
- [7.2. Levels](#72-levels)
- [7.2.1. Level 0 - Deprecated](#721-level-0--deprecated)
- [7.2.2. Level 1 - Experimental](#722-level-1--experimental)
- [7.2.3. Level 2 - Stable](#723-level-2--stable)
- [7.2.4. Level 3 - Legacy](#724-level-3--legacy)
- [7.3. Sub-Levels](#73-sub-levels)
- [7.3.1. 1.0 - Early Development](#731-10--early-development)
- [7.3.2. 1.1 - Active Development](#732-11--active-development)
- [7.3.3. 1.2 - Release Candidate](#733-12--release-candidate)
- [7.4. Multi-Line Indicators](#74-multi-line-indicators)
- [7.5. Inline Content](#75-inline-content)
- [7.6. Placement](#76-placement)
- [8. Type Annotations](#8-type-annotations)
- [8.1. Syntax](#81-syntax)
- [8.2. Parsing](#82-parsing)
- [8.3. Resolution](#83-resolution)
- [8.4. Rendering](#84-rendering)
- [9. Typed Parameter Lists](#9-typed-parameter-lists)
- [9.1. Identification](#91-identification)
- [9.2. Item Structure](#92-item-structure)
- [9.3. Special Prefixes](#93-special-prefixes)
- [9.3.1. `Returns:`](#931-returns)
- [9.3.2. `Extends:`](#932-extends)
- [9.3.3. `Type:`](#933-type)
- [9.4. Nested Properties](#94-nested-properties)
- [9.5. Default Values](#95-default-values)
- [9.6. Placement](#96-placement)
- [10. Code Blocks](#10-code-blocks)
- [10.1. Fence Style](#101-fence-style)
- [10.2. Info Strings](#102-info-strings)
- [10.3. The `displayName` Attribute](#103-the-displayname-attribute)
- [11. Links and Cross-References](#11-links-and-cross-references)
- [11.1. Reference-Style Links](#111-reference-style-links)
- [11.2. Cross-Document Links](#112-cross-document-links)
- [11.3. External Links](#113-external-links)
- [11.4. System-Call Auto-Linking](#114-system-call-auto-linking)
- [11.5. Type Auto-Linking](#115-type-auto-linking)
- [11.6. Link Reference Definitions](#116-link-reference-definitions)

---

## 1. Terminology and Conventions
Expand Down
6 changes: 1 addition & 5 deletions packages/core/src/generators/addon-verify/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,4 @@ The `addon-verify` generator extracts code blocks from `doc/api/addons.md` and g

## Configuring

The `addon-verify` generator accepts the following configuration options:

| Name | Type | Default | Description |
| -------- | -------- | ------- | -------------------------------------------------------- |
| `output` | `string` | - | The directory where extracted code files will be written |
- `output` {string} The directory where extracted code files will be written.
12 changes: 5 additions & 7 deletions packages/core/src/generators/api-links/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,8 @@ The `api-links` generator creates a mapping of publicly accessible functions to

## Configuring

The `api-links` generator accepts the following configuration options:

| Name | Type | Default | Description |
| ----------- | --------- | ------------------------------------ | --------------------------------------------------- |
| `output` | `string` | - | The directory where `apilinks.json` will be written |
| `sourceURL` | `string` | `'${GITHUB_BLOB_URL}lib/{fileName}'` | URL template for linking to source files |
| `minify` | `boolean` | Inherited from `global` | Whether to minify the output JSON |
- `output` {string} The directory where `apilinks.json` will be written.
- `sourceURL` {string} URL template for linking to source files.
**Default:** `'${GITHUB_BLOB_URL}lib/{fileName}'`.
- `minify` {boolean} Whether to minify the output JSON. Inherited from
`global`. **Default:** `true`.
8 changes: 2 additions & 6 deletions packages/core/src/generators/ast-js/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,5 @@ The `ast-js` generator parses JavaScript source files into AST (Abstract Syntax

## Configuring

The `ast-js` generator accepts the following configuration options:

| Name | Type | Default | Description |
| -------- | -------------------- | ------- | ------------------------------------------------- |
| `input` | `string \| string[]` | - | Glob pattern(s) for the JavaScript files to parse |
| `ignore` | `string \| string[]` | - | Glob pattern(s) for files to exclude from parsing |
- `input` {string|string[]} Glob pattern(s) for the JavaScript files to parse.
- `ignore` {string|string[]} Glob pattern(s) for files to exclude from parsing.
8 changes: 2 additions & 6 deletions packages/core/src/generators/ast/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,5 @@ The `ast` generator parses Markdown API documentation files into AST (Abstract S

## Configuring

The `ast` generator accepts the following configuration options:

| Name | Type | Default | Description |
| -------- | -------------------- | ------- | ------------------------------------------------- |
| `input` | `string \| string[]` | - | Glob pattern(s) for the Markdown files to parse |
| `ignore` | `string \| string[]` | - | Glob pattern(s) for files to exclude from parsing |
- `input` {string|string[]} Glob pattern(s) for the Markdown files to parse.
- `ignore` {string|string[]} Glob pattern(s) for files to exclude from parsing.
9 changes: 3 additions & 6 deletions packages/core/src/generators/json-simple/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,6 @@ The `json-simple` generator creates a simplified JSON version of the API documen

## Configuring

The `json-simple` generator accepts the following configuration options:

| Name | Type | Default | Description |
| -------- | --------- | ----------------------- | --------------------------------------------------- |
| `output` | `string` | - | The directory where `api-docs.json` will be written |
| `minify` | `boolean` | Inherited from `global` | Whether to minify the output JSON |
- `output` {string} The directory where `api-docs.json` will be written.
- `minify` {boolean} Whether to minify the output JSON. Inherited from
`global`. **Default:** `true`.
19 changes: 10 additions & 9 deletions packages/core/src/generators/jsx-ast/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,13 @@ The `jsx-ast` generator converts MDAST (Markdown Abstract Syntax Tree) to JSX AS

## Configuring

The `jsx-ast` generator accepts the following configuration options:

| Name | Type | Default | Description |
| ---------------------- | --------- | -------- | ------------------------------------------------------------------------ |
| `ref` | `string` | `'main'` | Git reference/branch for linking to source files |
| `index` | `array` | - | Array of `{ section, api }` objects defining the documentation structure |
| `generateAllPage` | `boolean` | `true` | When `true`, creates a synthetic JSX AST entry for `all.html` |
| `generateIndexPage` | `boolean` | `true` | When `true`, creates a synthetic JSX AST entry for `index.html` |
| `generateNotFoundPage` | `boolean` | `true` | When `true`, creates a synthetic JSX AST entry for `404.html` |
- `ref` {string} Git reference/branch for linking to source files.
**Default:** `'main'`.
- `index` {Array} Array of `{ section, api }` objects defining the
documentation structure.
- `generateAllPage` {boolean} When `true`, creates a synthetic JSX AST entry
for `all.html`. **Default:** `true`.
- `generateIndexPage` {boolean} When `true`, creates a synthetic JSX AST entry
for `index.html`. **Default:** `true`.
- `generateNotFoundPage` {boolean} When `true`, creates a synthetic JSX AST
entry for `404.html`. **Default:** `true`.
15 changes: 7 additions & 8 deletions packages/core/src/generators/legacy-html-all/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,10 @@ The `legacy-html-all` generator creates a single `all.html` file containing all

## Configuring

The `legacy-html-all` generator accepts the following configuration options:

| Name | Type | Default | Description |
| -------------- | --------- | ---------------------------- | ---------------------------------------------- |
| `output` | `string` | - | The directory where `all.html` will be written |
| `templatePath` | `string` | Inherited from `legacy-html` | Path to the HTML template file |
| `minify` | `boolean` | Inherited from `global` | Whether to minify the output HTML |
| `version` | `object` | Inherited from `global` | Version object containing version information |
- `output` {string} The directory where `all.html` will be written.
- `templatePath` {string} Path to the HTML template file. Inherited from
`legacy-html`. **Default:** `'template.html'`.
- `minify` {boolean} Whether to minify the output HTML. Inherited from
`global`. **Default:** `true`.
- `version` {Object} Version object containing version information. Inherited
from `global`. **Default:** `process.version`.
27 changes: 15 additions & 12 deletions packages/core/src/generators/legacy-html/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,18 @@ The `legacy-html` generator creates legacy HTML documentation pages for Node.js

## Configuring

The `legacy-html` generator accepts the following configuration options:

| Name | Type | Default | Description |
| ----------------------- | ---------- | --------------------------------------------- | ------------------------------------------------------------------------ |
| `output` | `string` | - | The directory where HTML files and assets will be written |
| `templatePath` | `string` | `'template.html'` | Path to the HTML template file |
| `additionalPathsToCopy` | `string[]` | `['assets']` | Array of paths to copy to the output directory |
| `ref` | `string` | `'main'` | Git reference/branch for linking to source files |
| `pageURL` | `string` | `'{baseURL}/latest-{version}/api{path}.html'` | URL template for documentation page links |
| `editURL` | `string` | `'${GITHUB_EDIT_URL}/doc/api{path}.md'` | URL template for "edit this page" links |
| `index` | `array` | - | Array of `{ api, section }` objects defining the documentation structure |
| `minify` | `boolean` | Inherited from `global` | Whether to minify the output HTML |
- `output` {string} The directory where HTML files and assets will be written.
- `templatePath` {string} Path to the HTML template file.
**Default:** `'template.html'`.
- `additionalPathsToCopy` {string[]} Array of paths to copy to the output
directory. **Default:** `['assets']`.
- `ref` {string} Git reference/branch for linking to source files.
**Default:** `'main'`.
- `pageURL` {string} URL template for documentation page links.
**Default:** `'{baseURL}/latest-{version}/api{path}.html'`.
- `editURL` {string} URL template for "edit this page" links.
**Default:** `'${GITHUB_EDIT_URL}/doc/api{path}.md'`.
- `index` {Array} Array of `{ api, section }` objects defining the
documentation structure.
- `minify` {boolean} Whether to minify the output HTML. Inherited from
`global`. **Default:** `true`.
10 changes: 3 additions & 7 deletions packages/core/src/generators/legacy-json-all/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,6 @@ The `legacy-json-all` generator consolidates data from the `legacy-json` generat

## Configuring

The `legacy-json-all` generator accepts the following configuration options:

| Name | Type | Default | Description |
| -------- | --------- | ------- | ---------------------------------------------------- |
| `output` | `string` | - | The directory where `all.json` will be written |
| `minify` | `boolean` | `false` | Whether to minify the output JSON |
| `index` | `array` | - | Array of `{ api }` objects defining the module order |
- `output` {string} The directory where `all.json` will be written.
- `minify` {boolean} Whether to minify the output JSON. **Default:** `false`.
- `index` {Array} Array of `{ api }` objects defining the module order.
11 changes: 4 additions & 7 deletions packages/core/src/generators/legacy-json/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,7 @@ The `legacy-json` generator creates legacy JSON files for the API documentation

## Configuring

The `legacy-json` generator accepts the following configuration options:

| Name | Type | Default | Description |
| -------- | --------- | -------- | ------------------------------------------------ |
| `output` | `string` | - | The directory where JSON files will be written |
| `ref` | `string` | `'main'` | Git reference/branch for linking to source files |
| `minify` | `boolean` | `false` | Whether to minify the output JSON |
- `output` {string} The directory where JSON files will be written.
- `ref` {string} Git reference/branch for linking to source files.
**Default:** `'main'`.
- `minify` {boolean} Whether to minify the output JSON. **Default:** `false`.
12 changes: 5 additions & 7 deletions packages/core/src/generators/llms-txt/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,8 @@ The `llms-txt` generator creates a `llms.txt` file to provide information to Lar

## Configuring

The `llms-txt` generator accepts the following configuration options:

| Name | Type | Default | Description |
| -------------- | -------- | --------------------------------- | ---------------------------------------------- |
| `output` | `string` | - | The directory where `llms.txt` will be written |
| `templatePath` | `string` | `'template.txt'` | Path to the template file |
| `pageURL` | `string` | `'{baseURL}/latest/api{path}.md'` | URL template for documentation page links |
- `output` {string} The directory where `llms.txt` will be written.
- `templatePath` {string} Path to the template file.
**Default:** `'template.txt'`.
- `pageURL` {string} URL template for documentation page links.
**Default:** `'{baseURL}/latest/api{path}.md'`.
17 changes: 8 additions & 9 deletions packages/core/src/generators/man-page/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,11 @@ The `man-page` generator creates a Unix man page version of the Node.js CLI docu

## Configuring

The `man-page` generator accepts the following configuration options:

| Name | Type | Default | Description |
| ---------------------- | -------- | --------------------------- | ----------------------------------------------------- |
| `output` | `string` | - | The directory where the man page file will be written |
| `fileName` | `string` | `'node.1'` | Name of the output file |
| `cliOptionsHeaderSlug` | `string` | `'options'` | Slug for the CLI options header section |
| `envVarsHeaderSlug` | `string` | `'environment-variables-1'` | Slug for the environment variables header section |
| `templatePath` | `string` | `'template.1'` | Path to the man page template file |
- `output` {string} The directory where the man page file will be written.
- `fileName` {string} Name of the output file. **Default:** `'node.1'`.
- `cliOptionsHeaderSlug` {string} Slug for the CLI options header section.
**Default:** `'options'`.
- `envVarsHeaderSlug` {string} Slug for the environment variables header
section. **Default:** `'environment-variables-1'`.
- `templatePath` {string} Path to the man page template file.
**Default:** `'template.1'`.
7 changes: 2 additions & 5 deletions packages/core/src/generators/metadata/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,5 @@ The `metadata` generator creates a flattened list of metadata entries from API d

## Configuring

The `metadata` generator accepts the following configuration options:

| Name | Type | Default | Description |
| --------- | -------- | ---------------- | -------------------------------------------------- |
| `typeMap` | `string` | `'typeMap.json'` | URL or path to the type mapping configuration file |
- `typeMap` {string} URL or path to the type mapping configuration file.
**Default:** `'typeMap.json'`.
Loading
Loading