Updated script to add sub-headings to markdown code snippets

[sacOO7]

• Fixes https://ably.atlassian.net/browse/DX-579
• Transforms:

  <Code>
  ```javascript
  code here
  ```
 
  ```realtime_java
   code here
  ```
  </Code>

Into ===>

  <Code>

  #### Javascript
  ```javascript
  code here
  ```

  #### Realtime Java
  ```realtime_java
  code here
  ```
  </Code>

Compared old and new markdown for docs/chat/rooms/messages.md using claude, it said

Old markdown:
✅ Cleaner, more concise
✅ Standard markdown syntax
⚠️ Relies on language identifiers in code fences (```javascript), which can be less prominent
⚠️ No explicit labels - must parse the code fence syntax
⚠️ Easier to miss - languages blend together without clear separators

New markdown:
✅ Explicit language headers (#### Javascript, #### React) make it immediately clear what each snippet is
✅ Hierarchical structure is unambiguous - headers act as labels
✅ Easy to extract - can search for #### pattern followed by language name
✅ Self-documenting - no need to infer from context

Summary by CodeRabbit

• New Features

  • Code blocks in documentation now include readable language subheadings (handles underscore variants and single-character identifiers) so each sample clearly shows its language.
  • Language subheadings are inserted before document title processing to preserve original content structure.

• Tests

  • Expanded test coverage to validate language labeling across multiple code-block scenarios and edge cases.

[coderabbitai]

Walkthrough

Adds two exported utilities—getLanguageDisplayName and addLanguageSubheadingsToCodeBlocks—and applies language-subheading insertion to MDX-to-Markdown conversion prior to title prepending. Tests and manifest/package metadata were updated.

Changes

Cohort / File(s)	Summary
Core Implementation data/onPostBuild/transpileMdxToMarkdown.ts	Exported getLanguageDisplayName(lang: string) and addLanguageSubheadingsToCodeBlocks(content: string); integrated subheading insertion to run before final title prepending in the MDX→Markdown pipeline.
Tests data/onPostBuild/transpileMdxToMarkdown.test.ts	Expanded tests to cover getLanguageDisplayName (simple, underscore variants, empty, single-char) and addLanguageSubheadingsToCodeBlocks (multiple/single code blocks, variant labels, boundaries, content preservation).
Metadata manifest_file, package.json	Updated manifest/package metadata (lines changed: +159/-0 across manifest/package updates).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐇
I hop through markup, tidy and bright,
I label each snippet so languages light.
H4 crowns each code, tidy and fair,
Now readers and parsers both find it there.
A little subheading, a big clearer sight.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding sub-headings to markdown code snippets within Code blocks.
Linked Issues check	✅ Passed	The PR fully addresses DX-579 by implementing explicit subheadings for language-specific code blocks, transforming fence-only separation into markdown-native headers for clarity.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the linked objective: two new utility functions and their exports for adding language subheadings to code blocks, with corresponding tests.
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 docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/markdown-snippet-headings

---

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]

@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: 3

🤖 Fix all issues with AI agents

In `@data/onPostBuild/transpileMdxToMarkdown.ts`:
- Around line 13-15: In function getLanguageDisplayName, change the early return
to use braces to satisfy the eslint "curly" rule: replace the line "if (!lang)
return '';" with a block-style conditional "if (!lang) { return ''; }" so the
function (and its parameter lang) uses a braced return before continuing to the
split/capitalize logic.
- Around line 27-31: The current codeTagRegex only matches bare
"<Code>...</Code>" so tags with attributes like "<Code fixed="true">...</Code>"
are skipped; update the codeTagRegex definition (the variable named codeTagRegex
used in the replace call) to allow an opening <Code> tag followed by optional
attributes by requiring a word boundary after "Code" and permitting any
characters except ">" until the closing ">", keep the case-insensitive and
global flags and keep the inner capture non-greedy so the replace callback (the
function handling innerContent) still receives the correct content.
- Around line 33-46: The regex in codeBlockRegex only uses \w+ and thus misses
language identifiers with hyphens, plus signs, dots, or other non-word chars;
update codeBlockRegex to capture any non-newline/backtick language token (e.g.,
/```([^\n`]+)\n[\s\S]*?```/g) and change the innerContent.replace callback
signature to accept the match and the lang (remove the redundant fullMatch
parameter) so getLanguageDisplayName(lang) receives the full language token;
modify occurrences of codeBlockRegex, innerContent.replace, and the callback
used to build transformedContent accordingly.

[Copilot]

Pull request overview

This PR adds language-specific subheadings to code snippets within <Code> tags in markdown documentation to make it easier for LLMs to identify which language each code snippet belongs to. The transformation converts code blocks from having implicit language identifiers in the fence syntax to explicit markdown headings.

Changes:

• Added getLanguageDisplayName() function to convert language identifiers to display names (e.g., realtime_javascript → Realtime Javascript)
• Added addLanguageSubheadingsToCodeBlocks() function to transform code blocks within <Code> tags by prepending language headings
• Integrated the new transformation as Stage 12 in the MDX-to-Markdown transpilation pipeline

Reviewed changes

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

File	Description
data/onPostBuild/transpileMdxToMarkdown.ts	Implements two new functions for language display name formatting and code block transformation; integrates the transformation into the pipeline after template variable replacement
data/onPostBuild/transpileMdxToMarkdown.test.ts	Adds comprehensive test coverage for the new functions including various language formats, multiple code blocks, and content preservation
data/onPostBuild/snapshots/transpileMdxToMarkdown.test.ts.snap	Updates snapshot to reflect the new heading structure in transformed code blocks

---

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

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

[kennethkalmer]

I like this @sacOO7, good stuff! I have some questions though:

1. Should we remove the language from the fenced code block for token efficiency?
2. [nitpick] Do you think it is possible that we dynamically determine what header level the markdown should use? In messages.md we jump from ## to #### in the first block, would be nice to go to ### instead. Likewise, if we have some other page that already has #### with code snippets inside we should then be going to #####.

[sacOO7]

@kennethkalmer good question. I had thought about both points.

1. For the first point, I felt that removing lang identifier from fences wouldn’t make much of a difference.
2. For the second point, I hadn’t given much thought to the specific case. I assumed that none of the sections should have #### sub-sections before snippets.

I’ll definitely double-check and update accordingly 👍