Skip to content

Commit e46e3cf

Browse files
avivkelleravivkeller
authored
chore(docs): ui improvements (#993)
1 parent d3306a2 commit e46e3cf

18 files changed

Lines changed: 185 additions & 298 deletions

File tree

‎docs/specification.md‎

Lines changed: 0 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -19,110 +19,6 @@ meaning by this specification (e.g., blockquotes as stability indicators,
1919
unordered lists as typed parameter lists), that special meaning is documented
2020
in the relevant section.
2121

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

12824
## 1. Terminology and Conventions

‎packages/core/src/generators/addon-verify/README.md‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,4 @@ The `addon-verify` generator extracts code blocks from `doc/api/addons.md` and g
44

55
## Configuring
66

7-
The `addon-verify` generator accepts the following configuration options:
8-
9-
| Name | Type | Default | Description |
10-
| -------- | -------- | ------- | -------------------------------------------------------- |
11-
| `output` | `string` | - | The directory where extracted code files will be written |
7+
- `output` {string} The directory where extracted code files will be written.

‎packages/core/src/generators/api-links/README.md‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,8 @@ The `api-links` generator creates a mapping of publicly accessible functions to
44

55
## Configuring
66

7-
The `api-links` generator accepts the following configuration options:
8-
9-
| Name | Type | Default | Description |
10-
| ----------- | --------- | ------------------------------------ | --------------------------------------------------- |
11-
| `output` | `string` | - | The directory where `apilinks.json` will be written |
12-
| `sourceURL` | `string` | `'${GITHUB_BLOB_URL}lib/{fileName}'` | URL template for linking to source files |
13-
| `minify` | `boolean` | Inherited from `global` | Whether to minify the output JSON |
7+
- `output` {string} The directory where `apilinks.json` will be written.
8+
- `sourceURL` {string} URL template for linking to source files.
9+
**Default:** `'${GITHUB_BLOB_URL}lib/{fileName}'`.
10+
- `minify` {boolean} Whether to minify the output JSON. Inherited from
11+
`global`. **Default:** `true`.

‎packages/core/src/generators/ast-js/README.md‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,5 @@ The `ast-js` generator parses JavaScript source files into AST (Abstract Syntax
44

55
## Configuring
66

7-
The `ast-js` generator accepts the following configuration options:
8-
9-
| Name | Type | Default | Description |
10-
| -------- | -------------------- | ------- | ------------------------------------------------- |
11-
| `input` | `string \| string[]` | - | Glob pattern(s) for the JavaScript files to parse |
12-
| `ignore` | `string \| string[]` | - | Glob pattern(s) for files to exclude from parsing |
7+
- `input` {string|string[]} Glob pattern(s) for the JavaScript files to parse.
8+
- `ignore` {string|string[]} Glob pattern(s) for files to exclude from parsing.

‎packages/core/src/generators/ast/README.md‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,5 @@ The `ast` generator parses Markdown API documentation files into AST (Abstract S
44

55
## Configuring
66

7-
The `ast` generator accepts the following configuration options:
8-
9-
| Name | Type | Default | Description |
10-
| -------- | -------------------- | ------- | ------------------------------------------------- |
11-
| `input` | `string \| string[]` | - | Glob pattern(s) for the Markdown files to parse |
12-
| `ignore` | `string \| string[]` | - | Glob pattern(s) for files to exclude from parsing |
7+
- `input` {string|string[]} Glob pattern(s) for the Markdown files to parse.
8+
- `ignore` {string|string[]} Glob pattern(s) for files to exclude from parsing.

‎packages/core/src/generators/json-simple/README.md‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,6 @@ The `json-simple` generator creates a simplified JSON version of the API documen
44

55
## Configuring
66

7-
The `json-simple` generator accepts the following configuration options:
8-
9-
| Name | Type | Default | Description |
10-
| -------- | --------- | ----------------------- | --------------------------------------------------- |
11-
| `output` | `string` | - | The directory where `api-docs.json` will be written |
12-
| `minify` | `boolean` | Inherited from `global` | Whether to minify the output JSON |
7+
- `output` {string} The directory where `api-docs.json` will be written.
8+
- `minify` {boolean} Whether to minify the output JSON. Inherited from
9+
`global`. **Default:** `true`.

‎packages/core/src/generators/jsx-ast/README.md‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,13 @@ The `jsx-ast` generator converts MDAST (Markdown Abstract Syntax Tree) to JSX AS
44

55
## Configuring
66

7-
The `jsx-ast` generator accepts the following configuration options:
8-
9-
| Name | Type | Default | Description |
10-
| ---------------------- | --------- | -------- | ------------------------------------------------------------------------ |
11-
| `ref` | `string` | `'main'` | Git reference/branch for linking to source files |
12-
| `index` | `array` | - | Array of `{ section, api }` objects defining the documentation structure |
13-
| `generateAllPage` | `boolean` | `true` | When `true`, creates a synthetic JSX AST entry for `all.html` |
14-
| `generateIndexPage` | `boolean` | `true` | When `true`, creates a synthetic JSX AST entry for `index.html` |
15-
| `generateNotFoundPage` | `boolean` | `true` | When `true`, creates a synthetic JSX AST entry for `404.html` |
7+
- `ref` {string} Git reference/branch for linking to source files.
8+
**Default:** `'main'`.
9+
- `index` {Array} Array of `{ section, api }` objects defining the
10+
documentation structure.
11+
- `generateAllPage` {boolean} When `true`, creates a synthetic JSX AST entry
12+
for `all.html`. **Default:** `true`.
13+
- `generateIndexPage` {boolean} When `true`, creates a synthetic JSX AST entry
14+
for `index.html`. **Default:** `true`.
15+
- `generateNotFoundPage` {boolean} When `true`, creates a synthetic JSX AST
16+
entry for `404.html`. **Default:** `true`.

‎packages/core/src/generators/legacy-html-all/README.md‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,10 @@ The `legacy-html-all` generator creates a single `all.html` file containing all
44

55
## Configuring
66

7-
The `legacy-html-all` generator accepts the following configuration options:
8-
9-
| Name | Type | Default | Description |
10-
| -------------- | --------- | ---------------------------- | ---------------------------------------------- |
11-
| `output` | `string` | - | The directory where `all.html` will be written |
12-
| `templatePath` | `string` | Inherited from `legacy-html` | Path to the HTML template file |
13-
| `minify` | `boolean` | Inherited from `global` | Whether to minify the output HTML |
14-
| `version` | `object` | Inherited from `global` | Version object containing version information |
7+
- `output` {string} The directory where `all.html` will be written.
8+
- `templatePath` {string} Path to the HTML template file. Inherited from
9+
`legacy-html`. **Default:** `'template.html'`.
10+
- `minify` {boolean} Whether to minify the output HTML. Inherited from
11+
`global`. **Default:** `true`.
12+
- `version` {Object} Version object containing version information. Inherited
13+
from `global`. **Default:** `process.version`.

‎packages/core/src/generators/legacy-html/README.md‎

Lines changed: 15 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,18 @@ The `legacy-html` generator creates legacy HTML documentation pages for Node.js
44

55
## Configuring
66

7-
The `legacy-html` generator accepts the following configuration options:
8-
9-
| Name | Type | Default | Description |
10-
| ----------------------- | ---------- | --------------------------------------------- | ------------------------------------------------------------------------ |
11-
| `output` | `string` | - | The directory where HTML files and assets will be written |
12-
| `templatePath` | `string` | `'template.html'` | Path to the HTML template file |
13-
| `additionalPathsToCopy` | `string[]` | `['assets']` | Array of paths to copy to the output directory |
14-
| `ref` | `string` | `'main'` | Git reference/branch for linking to source files |
15-
| `pageURL` | `string` | `'{baseURL}/latest-{version}/api{path}.html'` | URL template for documentation page links |
16-
| `editURL` | `string` | `'${GITHUB_EDIT_URL}/doc/api{path}.md'` | URL template for "edit this page" links |
17-
| `index` | `array` | - | Array of `{ api, section }` objects defining the documentation structure |
18-
| `minify` | `boolean` | Inherited from `global` | Whether to minify the output HTML |
7+
- `output` {string} The directory where HTML files and assets will be written.
8+
- `templatePath` {string} Path to the HTML template file.
9+
**Default:** `'template.html'`.
10+
- `additionalPathsToCopy` {string[]} Array of paths to copy to the output
11+
directory. **Default:** `['assets']`.
12+
- `ref` {string} Git reference/branch for linking to source files.
13+
**Default:** `'main'`.
14+
- `pageURL` {string} URL template for documentation page links.
15+
**Default:** `'{baseURL}/latest-{version}/api{path}.html'`.
16+
- `editURL` {string} URL template for "edit this page" links.
17+
**Default:** `'${GITHUB_EDIT_URL}/doc/api{path}.md'`.
18+
- `index` {Array} Array of `{ api, section }` objects defining the
19+
documentation structure.
20+
- `minify` {boolean} Whether to minify the output HTML. Inherited from
21+
`global`. **Default:** `true`.

‎packages/core/src/generators/legacy-json-all/README.md‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,6 @@ The `legacy-json-all` generator consolidates data from the `legacy-json` generat
44

55
## Configuring
66

7-
The `legacy-json-all` generator accepts the following configuration options:
8-
9-
| Name | Type | Default | Description |
10-
| -------- | --------- | ------- | ---------------------------------------------------- |
11-
| `output` | `string` | - | The directory where `all.json` will be written |
12-
| `minify` | `boolean` | `false` | Whether to minify the output JSON |
13-
| `index` | `array` | - | Array of `{ api }` objects defining the module order |
7+
- `output` {string} The directory where `all.json` will be written.
8+
- `minify` {boolean} Whether to minify the output JSON. **Default:** `false`.
9+
- `index` {Array} Array of `{ api }` objects defining the module order.

0 commit comments

Comments
 (0)