From 74764dc721a4d94248c679ef4ec70eafdec9a649 Mon Sep 17 00:00:00 2001 From: Mohamed Shams El-Deen Date: Sun, 26 Jul 2026 23:17:09 +0300 Subject: [PATCH 1/2] fix: do not render headings with no content --- docs/specification.md | 3 +-- packages/core/src/generators/metadata/utils/parse.mjs | 2 +- packages/react/src/jsx-ast/utils/buildContent.mjs | 5 +++++ 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/specification.md b/docs/specification.md index 0b5b11c94..ced8fe9c5 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -117,8 +117,7 @@ reproduce literal output. A conforming [document][term-document] MUST contain elements in the following order. Items marked OPTIONAL MAY be omitted entirely. -1. **Title heading** (REQUIRED) - Exactly one [ATX heading][cm-atx-heading] - at depth 1. +1. **Title heading** (OPTIONAL) - An [ATX heading][cm-atx-heading] at depth 1. 2. **[Simple directives][§6.2]** (OPTIONAL) - Zero or more [HTML comment][cm-html-comment] directives providing [document][term-document]-level metadata. These MUST immediately follow diff --git a/packages/core/src/generators/metadata/utils/parse.mjs b/packages/core/src/generators/metadata/utils/parse.mjs index 72f0dd705..18e73f489 100644 --- a/packages/core/src/generators/metadata/utils/parse.mjs +++ b/packages/core/src/generators/metadata/utils/parse.mjs @@ -87,7 +87,7 @@ export const parseApiDoc = ({ path, tree, mdx = false }, typeMap) => { // Handles the normalisation URLs that reference to API doc files with .md extension visit(tree, UNIST.isMarkdownUrl, node => visitMarkdownLink(node)); - // If the document has no headings but it has content, we add a fake heading to the top + // If the document has no headings but it has content, we add a fake heading to the top, it will not be rendered if (headingNodes.length === 0 && tree.children.length > 0) { tree.children.unshift(createTree('heading', { depth: 1 }, [])); } diff --git a/packages/react/src/jsx-ast/utils/buildContent.mjs b/packages/react/src/jsx-ast/utils/buildContent.mjs index b06b70a9e..ec2a17904 100644 --- a/packages/react/src/jsx-ast/utils/buildContent.mjs +++ b/packages/react/src/jsx-ast/utils/buildContent.mjs @@ -151,6 +151,11 @@ export const extractHeadingContent = content => { * @param {import('unist').Node|null} changeElement - The change history element, if available */ export const createHeadingElement = (content, changeElement) => { + // If the heading is empty, we don't render it + if (!content.children || content.children.length === 0) { + return { type: 'text', value: '' }; + } + const { type, slug } = content.data; let headingContent = extractHeadingContent(content); From 114b02d1ea64ef9d4ccc4958fd4d227f868565f2 Mon Sep 17 00:00:00 2001 From: Mohamed Shams El-Deen Date: Wed, 29 Jul 2026 05:23:51 +0300 Subject: [PATCH 2/2] fixup! --- docs/specification.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/specification.md b/docs/specification.md index ced8fe9c5..7ac7b50e1 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -117,7 +117,7 @@ reproduce literal output. A conforming [document][term-document] MUST contain elements in the following order. Items marked OPTIONAL MAY be omitted entirely. -1. **Title heading** (OPTIONAL) - An [ATX heading][cm-atx-heading] at depth 1. +1. **Title heading** (OPTIONAL, RECOMMENDED) - An [ATX heading][cm-atx-heading] at depth 1. 2. **[Simple directives][§6.2]** (OPTIONAL) - Zero or more [HTML comment][cm-html-comment] directives providing [document][term-document]-level metadata. These MUST immediately follow @@ -173,7 +173,7 @@ NOT be used. #### 4.2.1. Depth 1 -The [document][term-document] title. Exactly one depth-1 heading MUST appear +The [document][term-document] title. Exactly one depth-1 heading SHOULD appear per document. #### 4.2.2. Depth 2