fix: do not render headings with no content

[moshams272]

Description

Currently, if an MDX page lacks an ATX H1 (e.g., when the h1 is built into a custom React component), doc-kit automatically injects an empty h1 to satisfy AST structural requirements and metadata generation.

However, this leads to an issue for MDX: if it renders its own custom h1 in a React component, the final HTML ends up with two h1 tags (one from doc-kit, one from the component), breaking SEO and Accessibility.

The current workaround involves forcing a # Heading in markdown and visually hiding it via CSS (sr-only), which is a hack.

This PR still injects an empty h1, but it doesn't render the empty headings in general to DOM.

Validation

Tested on webpack-doc-kit:

Before:

After:

Related Issues

None

Check List

• I have read the Contributing Guidelines and made commit messages that follow the guideline.
• I have run node --run test and all tests passed.
• I have check code formatting with node --run format & node --run lint.
• I've covered new added functionality with unit tests if necessary.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Jul 29, 2026 2:25am

[vercel]

@moshams272 is attempting to deploy a commit to the OpenJS Foundation Team on Vercel.

A member of the Team first needs to authorize it.

[cursor]

PR Summary

Low Risk
Rendering-only guard and documentation tweaks; metadata injection behavior is unchanged.

Overview
Empty headings no longer appear in generated HTML, which fixes duplicate <h1> on MDX pages that supply their own title in React while the parser still injects a structural depth-1 heading for metadata.

createHeadingElement returns an empty text node when a heading has no children, so the placeholder from parse.mjs (unchanged behavior: still added when a file has content but no headings) stays in the AST for parsing but is omitted from the DOM.

The spec now treats the depth-1 title as OPTIONAL, RECOMMENDED instead of REQUIRED, and depth-1 semantics use SHOULD rather than MUST for “exactly one” heading.

^{Reviewed by Cursor Bugbot for commit 66b522f. Bugbot is set up for automated code reviews on this repo. Configure here.}

[codecov]

Codecov Report

❌ Patch coverage is 50.00000% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.51%. Comparing base (7bd1b5b) to head (66b522f).
⚠️ Report is 5 commits behind head on main.

Files with missing lines	Patch %	Lines
src/generators/jsx-ast/utils/buildContent.mjs	40.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #944      +/-   ##
==========================================
+ Coverage   86.20%   86.51%   +0.31%     
==========================================
  Files         195      195              
  Lines       17674    17979     +305     
  Branches     1608     1634      +26     
==========================================
+ Hits        15235    15554     +319     
+ Misses       2433     2419      -14     
  Partials        6        6              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit a0c54a2. Configure here.}

[avivkeller]

Can you:

1. Make this not an option, we shouldn't render elements with no content in any case
2. Patch the docs + spec to remove the note about titleless pages?

[moshams272]

Can you:

1. Make this not an option, we shouldn't render elements with no content in any case
2. Patch the docs + spec to remove the note about titleless pages?

you mean for headings only, right?

[avivkeller]

yes sorry

[avivkeller]

Should we just remove this statement... Why are we adding a fake heading in the first place?

Then, createHeadings won't need a fast path

[moshams272]

Actually, I was thinking of that and searching for what the effect will be. Let me revise what I found.

[moshams272]

1. While traversing AST, in this file, parseApiDoc extracts content by visiting heading nodes visit(tree, UNIST.isHeading, (headingNode, index) => {...}}. It uses each heading as an anchor and slices the AST content between it and the next heading. If a document has no headings, the visit never fires, and parseApiDoc returns an empty array, which drops all the page content.

2. in type.d.ts, The MetadataEntry interface strictly requires heading: HeadingNode (it is not optional).

[avivkeller]

I see, so headings are required, I guess. In that case, we should make the default heading something like {project} Documentation, and then in webpack use CSS/postprocessing to remove it

[moshams272]

I just think of accessibility, SEO and other projects that will use doc-kit, instead of pushing elements to the DOM that serve zero visual purpose, we can handle it here.

In the end, that's your decision, guys 😅

[avivkeller]

Your right

[bmuenzenmeyer]

this feels very related to notions within #931

[avivkeller]

this feels very related to notions within #931

Sort of, yes. We have one page without a heading, since we add the heading via JSX