[mehnoorsiddiqui]

Closes #443

The problem

A content page that is not valid MDX (an unclosed <Cards>, a mismatched closing tag, a broken {…} expression) reached the author too late, or in a form they could not act on:

• portal serve started without a word. The browser showed "Failed to fetch dynamically imported module", and the real cause was only in the body of a 500 response. Vite did log it, but the CLI does not show the dev server's output.
• portal generate failed, but showed the raw tail of the build log: only the first broken page, under the project's temporary path, with bundler internals such as [plugin fumadocs-mdx:mdx], ?macro_id=… and errors: [Getter/Setter].

What changes

The CLI already parses every content page the way the build does, to check its front matter and images. It now also reports where an .mdx page stops being valid MDX:

• portal generate and portal serve refuse such pages at startup, before Vite is involved.

• serve checks again on every save in content/. A refused save leaves the last version the preview accepted in place.

• Every broken page is listed in one run, with its path relative to src, and the line and column. MDX's own wording is kept, without the parser's internal names:

  ■  Pages in '…/src' are not valid MDX:
       • 'content/components/cards.mdx', line 55, column 1: Expected a closing tag for `<Cards>`
       • 'content/components/steps.mdx', line 9, column 12: Could not parse expression: Unexpected token
     MDX stops at the first mistake in a page, so a page can have more after the one shown.
  

• MDX only notices an unclosed tag at the end of the page. It reports no location on the error and puts the tag's position in the message text instead, so the CLI reads the position from there. The page is reported at the tag's own line.

Not covered

• Only the first mistake per page. MDX's parser stops at the first error in a page, so a page with three unclosed <Cards> reports one, and the next appears once that one is fixed. The message says so. Listing every unclosed tag would need a tag-matching pass of our own, outside MDX, which could disagree with it.
• serve does not start over broken content. It reports the problem and exits, as it already does for other content problems.

How it was tested

• Unit tests for the parse (unclosed tag, mismatched closing tag, broken expression, HTML comment, valid .mdx and .md pages), for the content check, for PortalSourceContext at startup and on a save that is later fixed, and for the message.
• npm test passes, ESLint is clean, and APIMATIC_E2E=1 passes for portal-build and portal-serve, so every page in the existing fixtures passes the new check.
• The CLI parses with remark-mdx 3.1.1 and the same micromark extensions that @mdx-js/mdx 3.1.1 uses in the build, so both find the same syntax errors.

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
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