[WEB-4876] - accept markdown and plain text content types

[aralovelace]

WEB-4876
This page doesnt have Markdown button - https://ably.com/docs/chat/rooms/messages

The issue:

The PageHeader component allowed too much flexibility when checking whether content was markdown. It treated responses as markdown even when no content type was provided by the server, and it relied on the request path rather than the actual content type. As a result, non-markdown content such as HTML or JSON could be incorrectly handled as markdown when the content type was missing or misleading.

The fixes done in this PR:

• Only accepts content types that explicitly indicate markdown (text/markdown, application/markdown) or plain text (text/plain)
• Rejects empty content types and pathname-based checks
• Provides clearer error messages that include the pathname and received content type

To Test:

Example page that doesnt have Markdown
review app with fix - https://ably-docs-web-4876-fix--m0bwcs.herokuapp.com/docs/chat/rooms/messages

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

Enhanced resilience of markdown fetch in PageHeader component by adding explicit 404 handling, implementing permissive content-type validation supporting text/markdown, application/markdown, and text/plain, and improving error logging with detailed context while preventing crashes on malformed responses.

Changes

Cohort / File(s)	Summary
Markdown Fetch Resilience src/components/Layout/mdx/PageHeader.tsx	Added explicit 404 response handling to clear markdown content gracefully; replaced strict content-type validation with permissive multi-type acceptance (text/markdown, application/markdown, text/plain, empty, .md extensions) while still rejecting invalid types; refined error reporting with selective logging (suppressed for 404s, detailed for others) and maintained isMounted guards

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A markdown fetch that stumbles no more,
With graceful 404s and type checks galore,
Content-types welcomed, both strict and loose,
Errors now handled without a spruce,
Your docs shall load, smooth as morning dew ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change: accepting markdown and plain text content types, which directly addresses the linked issue about Markdown option visibility.
Linked Issues check	✅ Passed	The code changes implement permissive content-type handling (markdown, plain text, missing types) and 404 handling that directly address the Markdown visibility issue reported in WEB-4876.
Out of Scope Changes check	✅ Passed	All changes in PageHeader.tsx are scoped to markdown fetching and content-type validation, directly supporting the objective of fixing Markdown option visibility.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[aralovelace]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@src/components/Layout/mdx/PageHeader.tsx`:
- Around line 71-88: The .md suffix check uses location.pathname, which is the
page path and will rarely end with ".md"; update the logic that builds
isMarkdownType (where contentType and isMarkdownType are defined) to check the
actual fetch/request URL (use response.url or the original request URL) instead
of location.pathname—replace or augment the location.pathname.endsWith('.md')
test with response.url.endsWith('.md') (or equivalent) so the fetch that
requested "`${location.pathname}.md`" is correctly recognized as markdown.

[kennethkalmer]

Thanks @aralovelace, this looks good. The error handling is a bit verbose to my taste, but that is okay. Squash, rebase and

[sacOO7]

Suggested change

	// Alternative approach - request markdown explicitly
	const response = await fetch(`${location.pathname}.md`, {
	signal: abortController.signal,
	headers: { 'Accept': 'text/markdown' }
	});

New implementation respects Accept headers.

curl -I -H "Accept: text/markdown" https://ably.com/docs/platform.md

Earlier we were not sending anything, so it was defaulting to text/plain. This should also fix the issue.

[sacOO7]

If we go with this approach, we can keep earlier code that explictly checks for text/markdown
i.e.

if (!contentType || !contentType.includes('text/markdown')) {
      throw new Error(`Invalid content type: expected text/markdown, got ${contentType}`);
}

Newly added checks for development environments looks okay to me

[sacOO7]

LGTM ( change is optional, but enforces respecting Accept header )