[saeedjamshaid]

The problem

A .md page is Markdown without HTML. The build leaves out every piece of HTML in one: <br> and <details> as much as a component such as <Cards>, and with a block of HTML, the text inside it. It says nothing, so an author finds out from the published page.

Fumadocs compiles a .md page as plain Markdown, and sends HTML and components to .mdx pages (discussion #785). The portal keeps to that and warns instead.

Part of apimatic-io issue 2314, after #456, which loads an <img> in an .mdx page.

What changes

• portal generate and portal serve name each .md page with HTML or components, and say how to keep them: rename the page to .mdx, closing empty tags and writing comments as MDX does.
• A warning, not an error. The rest of the page builds, and one stray <br> shouldn't stop a build.
• Each piece of HTML is shown by the line it starts on, as written, such as <br> or <Callout type="warn">. That includes a line of text after a </div> or a comment, which the build drops with it. Not shown:
  • a piece of nothing but comments and closing tags, which leaves out nothing a reader would see;
  • code, inline code or an <https://…> link;
  • anything in an .mdx page.
• A page shows each piece once, up to three, and counts the rest. Forty <br> tags take one line, and a piece's line is cut at 60 characters, since one can run to a whole paragraph.
• Under portal serve, the warning comes again when a page gains a piece it didn't have, not when one moves to another line.
• LeftOutHtml holds a page's pieces. It answers what to show and whether a later version adds anything, so the prompt only prints.
• A page is parsed once, and its images and its HTML are read from one list of its nodes.

What it prints

▲  Some '.md' pages in 'src' have HTML or components, which the portal leaves out:
│    • 'content/authentication.md', line 12: '<br>'
│    • 'content/authentication.md', line 14: '<details>'
│    • 'content/authentication.md', line 23: '<Callout type="warn">'
│    • 'content/index.md', line 10: '<br>'
│  Rename each page to '.mdx' to keep them. MDX needs empty tags closed, such as '<br />', and comments written as '{/* … */}'.

With one page, it opens "A '.md' page in 'src' has", and says "Rename the page". A page with more than three pieces adds "and 2 more on this page".

Testing

• pnpm test with APIMATIC_E2E=1, as CI runs it: 2087 passing, ESLint clean.
• Unit:
  • the pieces of a .md page and their lines, including text after a closing tag, after a comment, and after an empty comment, <!--->;
  • what isn't named: comments, closing tags, code, links and .mdx pages;
  • LeftOutHtml: each piece once, up to three, a long line cut short, and when a later version adds nothing;
  • the notice from the content check, when portal serve gives it again, and the message for one page and several.
• Each rule fails a test when it's removed: dropping comments, dropping closing tags, reading an empty comment, showing a piece once, cutting a long line, and comparing by what's written rather than by line.
• Against the sub-path fixture, with HTML added to authentication.md and index.md, resolving it as portal generate does printed the warning above.
• No end-to-end test: the warning is printed before the build.

For #444

#444 changes the same files. This PR parses a page once and reads one list of its nodes per check, so #444's component check can read the same list.

Not in this PR

• Rendering HTML in .md pages, which apimatic-io issue 2314 decided against.
• The other changes a page needs as MDX, such as a { or < in the text. The build reports what MDX refuses.
• What a .md page shows as text instead of leaving out: a component with a {…} attribute, such as <Tabs items={[…]}>, an import line, or {/* … */}. The preview shows it, and the warning doesn't name it.
• The CLI reads a .md page without GitHub-flavoured Markdown, which the build adds. HTML indented under a footnote, for one, is dropped by the build and not named. The image check reads pages the same way.

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud