fix(docs): keep every snippet alone on its line so seven pages stop returning 500

[datlechin]

Seven live docs pages return HTTP 500. /switching was the one reported; probing all 115 nav entries found the rest.

500  switching
500  faq
500  features/plugins
500  features/change-tracking
500  features/table-structure
500  external-api/mcp-resources
500  external-api/mcp-prompts

Cause

A snippet is block content. Mintlify renders it as a block, and any prose sharing its line returns 500 in production while mint validate and the Mintlify deploy both report success.

The correlation is exact across the corpus. Every one of the 24 pages that imports a snippet and renders puts the call alone on its line. Every one of the 7 that returned 500 did not:

Page	What shared the line
switching, faq	a new sentence after
features/change-tracking, external-api/mcp-prompts	a new sentence after
features/table-structure	a markdown link after
external-api/mcp-resources	prose before and a link after
features/plugins	prose before

The snippet file itself is never the problem: driver-counts.mdx has three pages that render and three that did not, with a byte-identical <DriverCounts /> call in all six. Props are not the problem either: registry-plugin.mdx takes two props and its 17 pages all render.

Why the existing guard was green

docs/scripts/check-links.py already has a check_snippets check, added by #2375, and CI already runs it. It was built on a premise stated in its own docstring:

Starting a new sentence after one on the same line renders fine. Continuing the same sentence does not.

That premise is false. #2375 fixed features/table-structure.mdx by replacing ; with a new sentence starting with a markdown link, and the page kept returning 500 for the next day. The check only matched a CONTINUES pattern (a leading comma, semicolon, colon, paren, or one of seven conjunctions), so six of these seven pages passed it, and it never looked at text before the snippet at all, which is what features/plugins had.

What changed

The seven pages put their snippet on its own line.

check_snippets now rejects any prose on the line, before or after, and names which side. The docstring carries the evidence rather than the premise:

$ python3 docs/scripts/check-links.py      # each variant reintroduced in turn
after-continuation     caught=1     <- the only one the old check caught
after-new-sentence     caught=1
after-link             caught=1
before                 caught=1

Verification

Step	Result
docs/scripts/check-links.py	ok 115 navigation entries, 115 pages, every link resolves
docs/scripts/check-writing-style.sh	docs/ matches the house style
docs/scripts/check-docs-against-source.py	docs/ agrees with the source
Guard tested by reintroducing all four variants	all four caught

The 500s are served from a build of main, so they clear when this merges and the docs site redeploys. Worth re-probing the seven URLs afterwards.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
TablePro	🟢 Ready	View Preview	Aug 23, 2026, 2:35 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.