markdown-content-parity should distinguish intentional audience segmentation from unintentional content drift

[devalog]

Current behavior: The markdown-content-parity check assumes that any drift between markdown and HTML content means agents are getting outdated information and treats all divergence as a problem.

Problem: Content drift isn't always a deficiency. Some sites intentionally serve different content to different audiences — for example, using tags or other mechanisms to provide agent-optimized markdown alongside human-optimized HTML. In those cases, divergence is a feature, not a bug.

Desired behavior: The check should distinguish between two scenarios:

• Unintentional drift — markdown and HTML have fallen out of sync (the current assumption, and a real problem).
• Intentional audience segmentation — the site deliberately serves different content for agents vs. humans, e.g., through structured tags or metadata indicating the split is purposeful. For example, Fern specifically does this through <llms-only> and <llms-ignore> tags.

I don't have a specific implementation in mind, but roughly: the check should pass if markdown == HTML or if there's some evidence the content is intentionally segmented by audience.

[dacharyc]

Awesome - thanks for filing this issue, @devalog ! This is a good callout - it's a gap the spec should address. When I added the check, it was a response to build pipeline issues that were causing some of the content to be silently dropped on the markdown page, and this was meant to be a diagnostic for that. It doesn't consider the case you raise here about people intentionally building different versions of the page in HTML vs. markdown.

The Fern tags seem like a useful implementation detail. I'll have a think about how to update the spec language around this check to reflect the difference between "accidentally omitted" and "intentionally excluded," and maybe I'll borrow Fern's implementation for the afdocs check as a concrete way of distinguishing these cases.

[dacharyc]

Hey @devalog - I've been considering this more and I think there are a few directions we could go. Curious for your thoughts.

Restating your issue, the problem is that the check assumes markdown should mirror HTML, but some sites intentionally serve different content per audience. Two approaches that could work together:

1. Recognize audience-segmentation tags in the content.

If the HTML uses tags like Fern's / to control what appears in each version, the check should account for them. Before comparing, strip content that's explicitly tagged for one audience. If the remaining shared content is in parity, pass. The spec would define a set of recognized tag conventions (starting with Fern's as the clearest existing example) and leave room for implementations to recognize additional ones.

2. A content-mode declaration for the page.

Sites could signal that a page's markdown is intentionally curated rather than mirrored. A few options for where this could live:

• Response header on the markdown endpoint, e.g. X-Content-Mode: curated. Works for any server, but static hosts make custom headers awkward and CDNs can strip them.
• Frontmatter in the markdown response, e.g. content-mode: curated. Travels with the content and can't be stripped, but not every site uses frontmatter.
• Tooling configuration. Rather than requiring sites to change their content or headers, the spec could define a config-level setting (like AFDocs' existing config file) where a site owner declares that their markdown is curated. This doesn't require any upstream changes but only works for sites running the checks themselves.

When content-mode is curated (however declared), the parity check would relax or skip entirely for that page. When it's mirrored (the default if nothing is declared), the check runs with current thresholds.

These aren't mutually exclusive. Option 1 handles the case where segmentation is visible in the markup. Option 2 handles cases where it isn't (the markdown is just different, with no tags to prove it). Thoughts?

[devalog]

@dacharyc This sounds great to me, thanks so much for looking into this! Of the options you laid out, I see 1. as the strongest starting point — it recognizes what Fern is already building natively and rewards that approach (I'd love to see other platforms implement audience-segmentation tags too). For the options listed in 2. I'd lean toward the tooling config as the best complement. The header and frontmatter options would put the burden on individual site owners to add conventions to their own content, which feels like something better solved at the platform level. Tooling config keeps the responsibility in the check itself, which seems like the most practical fallback.

[devalog]

Mintlify now does content filtering as well: https://www.mintlify.com/docs/components/visibility

[dacharyc]

Awesome, thanks for pointing this out, @devalog !

Sorry I have been slow getting to this; I'm working through a bug backlog at the moment in afdocs but I think I'm just about back to "feature request" territory, so I should have time to make this spec addition and afdocs enhancement soon. 🤞