From bee146ce9b05c754ebfae8a4dcd868b4884ae2d3 Mon Sep 17 00:00:00 2001 From: Mohamed Shams El-Deen Date: Sun, 26 Jul 2026 23:17:09 +0300 Subject: [PATCH] fix: do not render headings with no content --- docs/specification.md | 3 +-- src/generators/jsx-ast/utils/buildContent.mjs | 5 +++++ src/generators/metadata/utils/parse.mjs | 2 +- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/specification.md b/docs/specification.md index 7ff09cb3..ebf88048 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -221,8 +221,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/src/generators/jsx-ast/utils/buildContent.mjs b/src/generators/jsx-ast/utils/buildContent.mjs index dd621eec..631dc090 100644 --- a/src/generators/jsx-ast/utils/buildContent.mjs +++ b/src/generators/jsx-ast/utils/buildContent.mjs @@ -132,6 +132,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); diff --git a/src/generators/metadata/utils/parse.mjs b/src/generators/metadata/utils/parse.mjs index 72f0dd70..18e73f48 100644 --- a/src/generators/metadata/utils/parse.mjs +++ b/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 }, [])); }