fix(html): list pages without a document-level stability index

.changeset/index-page-missing-docs.md

@@ -0,0 +1,5 @@
+---
+'@doc-kit/generator-react': patch
+---
+
+fix(html): list pages without a document-level stability index

packages/react/src/html/ui/components/DocumentationIndex/index.jsx

@@ -9,7 +9,8 @@ import { documentationIndex } from '#theme/config';
  * @typedef {Object} DocumentationIndexEntry
  * @property {string} api - Basename of the document, linked as `${api}.html`
  * @property {string} name - Human-readable name from the document's heading
- * @property {string} index - Stability index (e.g. `'2'` or `'1.1'`)
+ * @property {string} [index] - Stability index (e.g. `'2'` or `'1.1'`), absent
+ * on documents that carry stability only on their individual sections
  * @property {string} [description] - The document's `llm_description`, or its
  * first paragraph, rendered to HTML at build time
  */
@@ -26,13 +27,15 @@ const IndexEntry = ({ api, name, index, description }) => {
       <span className={styles.title}>
         <span className={styles.name}>{name}</span>
 
-        <Badge
-          size="small"
-          kind={STABILITY_KINDS[level] ?? 'neutral'}
-          aria-label={`Stability: ${index}`}
-        >
-          {label}
-        </Badge>
+        {index !== undefined && (
+          <Badge
+            size="small"
+            kind={STABILITY_KINDS[level] ?? 'neutral'}
+            aria-label={`Stability: ${index}`}
+          >
+            {label}
+          </Badge>
+        )}
       </span>
 
       {description && (

packages/react/src/html/utils/__tests__/config.test.mjs

@@ -52,6 +52,7 @@ const makeEntry = (api, name, path, extra = {}) => ({
   api,
   path,
   heading: { depth: 1, data: { name } },
+  content: { type: 'root', children: [] },
   ...extra,
 });
 
@@ -131,7 +132,7 @@ describe('buildPageList', () => {
 });
 
 describe('buildDocumentationIndex', () => {
-  it('lists only pages with a stability index, with their descriptions', () => {
+  it('lists every page but the index itself, with their descriptions', () => {
     const input = [
       {
         api: 'fs',
@@ -183,6 +184,46 @@ describe('buildDocumentationIndex', () => {
     ]);
   });
 
+  it('keeps pages that carry no document-level stability index', () => {
+    // `process` and `errors` are documented this way: stability lives on their
+    // individual sections rather than on the document.
+    const input = [
+      {
+        api: 'process',
+        path: '/process',
+        heading: { depth: 1, data: { name: 'Process' } },
+        stability: null,
+        llm_description: 'Information about the current process.',
+        content: { type: 'root', children: [] },
+      },
+      {
+        api: 'fs',
+        path: '/fs',
+        heading: { depth: 1, data: { name: 'File System' } },
+        stability: { data: { index: '2' } },
+        llm_description: 'File system APIs.',
+        content: { type: 'root', children: [] },
+      },
+    ];
+
+    const result = buildDocumentationIndex(input);
+
+    assert.deepStrictEqual(result, [
+      {
+        api: 'fs',
+        name: 'File System',
+        index: '2',
+        description: 'File system APIs.',
+      },
+      {
+        api: 'process',
+        name: 'Process',
+        index: undefined,
+        description: 'Information about the current process.',
+      },
+    ]);
+  });
+
   it('renders descriptions to HTML, without the links entries cannot nest', () => {
     const input = [
       {

packages/react/src/html/utils/config.mjs

@@ -116,18 +116,22 @@ export function buildChunkGroups(input) {
 
 /**
  * Pre-compute the entries rendered by the `<DocumentationIndex />` component:
- * every page with a stability index, plus its description.
+ * every page other than the index itself, plus its description.
+ *
+ * A document-level stability index is optional. Documents such as `process`
+ * and `errors` carry stability only on their individual sections, and pages
+ * that list them by document, this one included, still need to link to them.
  *
  * @param {Array<import('@doc-kit/core/generators/metadata/types').MetadataEntry>} input
- * @returns {Array<{api: string, name: string, index: string, description: string}>}
+ * @returns {Array<{api: string, name: string, index: string | undefined, description: string}>}
  */
 export function buildDocumentationIndex(input) {
   return getSortedHeadNodes(input)
-    .filter(entry => entry.stability)
+    .filter(entry => entry.api !== 'index')
     .map(entry => ({
       api: entry.api,
       name: entry.heading.data.name,
-      index: entry.stability.data.index,
+      index: entry.stability?.data.index,
       description: renderAsHTML(parseInline(getEntryDescription(entry), true)),
     }));
 }