Fix generated markdown pages to have absolute URL path

[sacOO7]

• Fixes https://ably.atlassian.net/browse/FTF-552
• e.g. https://ably.com/docs/chat/getting-started.md currently has /docs/getting-started/javascript, instead it should be ably.com/docs/getting-started/javascript.md

Summary by CodeRabbit

• New Features

  • Improved docs link conversion: JSX-style links are automatically converted to Markdown with readable link text, support for absolute site URLs, and preservation of code blocks and hidden content.

• Tests

  • Added comprehensive test coverage for docs path conversions, JSX link prop transformations, code-block handling, external URLs, and other edge cases.

[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.

• 🔍 Trigger a full review

Walkthrough

Added code-block-aware text-transform utilities and two new public functions—generateLinkTextFromPath and convertJsxLinkProps—into the MDX-to-Markdown pipeline; several removal/transform helpers were refactored to preserve fenced code blocks. Tests expanded to cover the new functions and scenarios.

Changes

Cohort / File(s)	Summary
MDX → Markdown transformations data/onPostBuild/transpileMdxToMarkdown.ts	Introduced splitByCodeBlocks and transformNonCodeBlocks to operate only on non-code sections. Refactored removal helpers (script, anchor, hidden-from-tables, JSX comments) to use the new transformer. Added and exported generateLinkTextFromPath(urlPath: string) and convertJsxLinkProps(content: string, siteUrl: string). Integrated convertJsxLinkProps into the MDX pipeline (new Stage 9) and renumbered subsequent stages.
Tests data/onPostBuild/transpileMdxToMarkdown.test.ts	Expanded tests to import and validate generateLinkTextFromPath and convertJsxLinkProps across multiple cases (docs paths, JSX link props, code-block preservation, external URLs, edge cases).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I nibble paths and gentle props,
Preserving fences, skipping stops,
I craft link text from doclike trails,
Convert JSX so markdown sails,
Hop on—these changes leave neat trails. ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: fixing generated markdown pages to use absolute URL paths instead of relative ones, which aligns with the PR's core objective.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

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

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/markdown-page-relative-paths

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[sacOO7]

File: docs/getting-started.md
Title: Getting started with Pub/Sub

Original: '/docs/getting-started/javascript'
Converted: 'ably docs getting-started javascript'

Original: '/docs/getting-started/node'
Converted: 'ably docs getting-started node'

Original: '/docs/getting-started/react'
Converted: 'ably docs getting-started react'

Original: '/docs/getting-started/react-native'
Converted: 'ably docs getting-started react-native'

Original: '/docs/getting-started/kotlin'
Converted: 'ably docs getting-started kotlin'

Original: '/docs/getting-started/swift'
Converted: 'ably docs getting-started swift'

Original: '/docs/getting-started/objective-c'
Converted: 'ably docs getting-started objective-c'

Original: '/docs/getting-started/go'
Converted: 'ably docs getting-started go'

Original: '/docs/getting-started/java'
Converted: 'ably docs getting-started java'

Original: '/docs/getting-started/python'
Converted: 'ably docs getting-started python'

Original: '/docs/getting-started/flutter'
Converted: 'ably docs getting-started flutter'

Original: '/docs/getting-started/ruby'
Converted: 'ably docs getting-started ruby'

Original: '/docs/getting-started/dotnet'
Converted: 'ably docs getting-started dotnet'

Original: '/docs/getting-started/php'
Converted: 'ably docs getting-started php'

Original: '/docs/getting-started/laravel'
Converted: 'ably docs getting-started laravel'

---

File: docs/chat/getting-started.md
Title: Getting started with Chat

Original: '/docs/chat/getting-started/javascript'
Converted: 'ably docs chat getting-started javascript'

Original: '/docs/chat/getting-started/react'
Converted: 'ably docs chat getting-started react'

Original: '/docs/chat/getting-started/react-native'
Converted: 'ably docs chat getting-started react-native'

Original: '/docs/chat/getting-started/android'
Converted: 'ably docs chat getting-started android'

Original: '/docs/chat/getting-started/jvm'
Converted: 'ably docs chat getting-started jvm'

Original: '/docs/chat/getting-started/swift'
Converted: 'ably docs chat getting-started swift'

Original: '/docs/chat/getting-started/react-ui-kit'
Converted: 'ably docs chat getting-started react-ui-kit'

---

File: docs/ai-transport.md
Title: About AI Transport

Original: '/docs/guides/ai-transport/openai-message-per-response'
Converted: 'ably docs guides ai-transport openai-message-per-response'

Original: '/docs/guides/ai-transport/openai-message-per-token'
Converted: 'ably docs guides ai-transport openai-message-per-token'

Original: '/docs/guides/ai-transport/anthropic-message-per-response'
Converted: 'ably docs guides ai-transport anthropic-message-per-response'

Original: '/docs/guides/ai-transport/anthropic-message-per-token'
Converted: 'ably docs guides ai-transport anthropic-message-per-token'

Original: '/docs/guides/ai-transport/vercel-message-per-token'
Converted: 'ably docs guides ai-transport vercel-message-per-token'

Original: '/docs/guides/ai-transport/lang-graph-message-per-token'
Converted: 'ably docs guides ai-transport lang-graph-message-per-token'

[sacOO7]

@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 `@data/onPostBuild/transpileMdxToMarkdown.ts`:
- Around line 448-463: convertJsxLinkProps currently replaces /docs/ paths
inside fenced code blocks, breaking code samples; fix it by splitting the input
into parts that preserve fenced code blocks before running the regex
replacement: inside convertJsxLinkProps use the same fenceRegex/code-block
splitting pattern used by removeScriptTags/removeAnchorTags (collect parts with
isCodeBlock flag by iterating matchAll over the fence regex), leave parts where
isCodeBlock === true untouched, and only run the /(['"])(\/docs\/[^'"]+)\1/g
replacement on non-code parts to produce absolute links using
generateLinkTextFromPath and baseUrl.

🧹 Nitpick comments (1)

data/onPostBuild/transpileMdxToMarkdown.test.ts (1)

459-541: Consider adding a test for code block preservation.

The test suite thoroughly covers JSX prop transformations, but lacks coverage for content inside fenced code blocks. Documentation pages may include code examples showing how to use components with /docs/ paths - those should remain untransformed.

🧪 Suggested test case to add

it('should not convert /docs/ paths inside code blocks', () => {
  const input = `Here's an example:

\`\`\`jsx
{
  link: '/docs/channels'
}
\`\`\`

Real prop: link: '/docs/presence'`;
  const output = convertJsxLinkProps(input, siteUrl);
  // Code block content should be preserved
  expect(output).toContain("link: '/docs/channels'");
  // Non-code-block content should be converted
  expect(output).toContain(`link: '[ably docs presence](http://localhost:3000/docs/presence)'`);
});

[Copilot]

Pull request overview

This PR fixes an issue where JSX link props in MDX files (like link: '/docs/chat/getting-started/javascript') were not being properly converted to markdown links with absolute URLs and .md extensions in the generated markdown files.

Changes:

• Added generateLinkTextFromPath function to create readable link text from /docs/ URL paths
• Added convertJsxLinkProps function to convert quoted /docs/ URLs to markdown links with absolute URLs
• Integrated the new conversion as Stage 9 in the transformation pipeline (before adding .md extensions)

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
data/onPostBuild/transpileMdxToMarkdown.ts	Implemented two new functions (generateLinkTextFromPath and convertJsxLinkProps) to convert JSX link props to markdown links, integrated as Stage 9 in the transformation pipeline
data/onPostBuild/transpileMdxToMarkdown.test.ts	Added comprehensive test coverage for the two new functions, testing various input scenarios including single/double quotes, multiple links, and edge cases

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[kennethkalmer]

Small suggestion on a duplicate test so far. I'm gonna look into CodeRabbit's suggestion and see if I can find a code snippet that might show the issue. Copilot has some good suggestions to consider as well

[kennethkalmer]

@coderabbitai full review

[coderabbitai]

✅ Actions performed

Full review triggered.

[coderabbitai]

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

data/onPostBuild/transpileMdxToMarkdown.ts (1)

195-224: ⚠️ Potential issue | 🟡 Minor

Fix Prettier lint errors in the transform wrappers.

The linter expects a single-line arrow body in these calls; please reformat (or run Prettier) to satisfy the prettier/prettier errors.

🤖 Fix all issues with AI agents

In `@data/onPostBuild/transpileMdxToMarkdown.test.ts`:
- Around line 465-534: Prettier is failing on very long expectation lines in the
tests that call convertJsxLinkProps (see the "should convert ..." and "should
handle Tiles component content ..." tests); run Prettier or reformat those long
toBe(...) / toContain(...) expectation strings so they fit the project's
line-length rules (e.g., split long expected strings across
concatenated/template pieces or assign the expected value to a variable and
assert against that variable) to satisfy linting without changing the assertions
themselves.

In `@data/onPostBuild/transpileMdxToMarkdown.ts`:
- Around line 338-345: The generateLinkTextFromPath function produces "ably docs
docs" for "/docs" and a trailing space for "/docs/"; fix it by stripping both
"/docs" and "/docs/" (e.g., use a regex that removes an optional trailing slash)
and then checking if the resulting parts array is empty—if empty return "ably
docs" exactly, otherwise return `ably docs ${parts.join(' ')}`; update
generateLinkTextFromPath to perform these two checks so root docs paths are
handled cleanly.
- Around line 354-364: convertJsxLinkProps currently calls
transformNonCodeBlocks which skips fenced/code blocks and so misses converting
'/docs/...' occurrences; replace that by running the same replacement against
the full content (or add an optional flag to bypass transformNonCodeBlocks) so
all '/docs/...' strings are converted. Specifically, update convertJsxLinkProps
to operate on content directly (using the same regex
/(['"])(\/docs\/[^'"]+)\1/g, building absoluteUrl with siteUrl/baseUrl and
linkText via generateLinkTextFromPath) instead of passing the callback into
transformNonCodeBlocks.

[kennethkalmer]

Nicely done @sacOO7, thanks for making our markdown output better! ✨

[kennethkalmer]

😍