[WEB-4447] Generate markdown copies of each HTML file for agents

[kennethkalmer]

Description

PoC to generate markdown version of our generated HTML content to be more supportive of agentic workflows.

Checklist

• [ ] Commits have been rebased.
• [ ] Linting has been run against the changed file(s).
• [ ] The PR adheres to the writing style guide and contribution guide.

[coderabbitai[bot]]

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

✨ Finishing touches

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment
• [ ] Commit unit tests in branch WEB-4447-dot-html-dot-md

[!TIP]

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

• Provide your own instructions using the high_level_summary_instructions setting.
• Format the summary however you like (bullet lists, tables, multi-section layouts, contributor stats, etc.).
• Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example instruction:

"Divide the high-level summary into five sections:

1. 📝 Description — Summarize the main change in 50–60 words, explaining what was done.
2. 📓 References — List relevant issues, discussions, documentation, or related PRs.
3. 📦 Dependencies & Requirements — Mention any new/updated dependencies, environment variable changes, or configuration updates.
4. 📊 Contributor Summary — Include a Markdown table showing contributions: | Contributor | Lines Added | Lines Removed | Files Changed |
5. ✔️ Additional Notes — Add any extra reviewer context. Keep each section concise (under 200 words) and use bullet or numbered lists for clarity."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

---

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

[m-hulbert]

Thanks for taking a stab at this, Ken!

Not sure what level of feedback you're looking for, but;

• We'd need to enable the output to handle a query param for different languages, as it only supports the default at the moment.
• I think we should signal somewhere in the metadata the language the page was generated for once we sort that.
• Surprisingly the output doesn't handle tables even though we're not doing anything non-standard.
• We do use a non-standard component for code, so we'll need to something with that.
• Same for the aside syntax that we use - I wonder if we should just show the raw MDX rather than trying to do anything fancy.
• The textile output is a bit iffy, but that's to be expected and not something we should worry about.
• I think we should add a button to each page to view in MD once we nail this.

[m-hulbert]

This has been superseded by https://github.com/ably/docs/pull/3000