Native HTML README Rendering - Human Friendly Documentation

[asjadanis]

🏷️ Discussion Type

Product Feedback

Body

Problem

Since agentic development has been widely adopted, more and more code and documentation are being generated by agents. Markdown works well for agents, but lengthy, text-heavy documentation isn't always the best way for humans to understand a project.

HTML offers a richer way to present documentation through visual layouts, architecture diagrams, interactive elements, and better navigation. Agents can already generate these experiences with very little effort. It would be useful if GitHub supported rendering README.html alongside README.md, allowing repositories to offer both formats without requiring users to clone the repository or deploy GitHub Pages.

In the agentic era, READMEs should evolve beyond Markdown. For most of my projects, I have started generating a self-contained README.html with a more visual project walkthrough, and I imagine other engineers are doing something similar. Locally, it is considerably easier to explore than a long text document. On GitHub, though, the HTML file is shown as source. To see the actual document, readers have to download it, clone the repository, publish a separate site, or use a third-party preview service.

I'm not proposing that HTML replace Markdown, or that every project maintain two READMEs. I'd like repository authors to be able to choose the most useful presentation for their readers, directly in GitHub.

Feature request

1. Add a rendered Preview tab for .html files.

Alongside the existing source view, offer an in-repository preview for HTML documents. This would also benefit architecture reports, benchmark results, coverage reports, static demos, and other checked-in HTML artifacts.

2. Recognize README.html as an optional README presentation.

When a repository includes README.md and README.html, offer a simple Markdown / HTML choice in the README area, with Markdown remaining the default. If a repository only contains README.html, allow it to be presented as its README.

3. Support two preview modes.

• Static preview (default): Render HTML and CSS, but do not execute JavaScript.
• Interactive preview (explicit opt-in): Allow JavaScript for documents that need it, after the reader deliberately chooses to enable it for that preview. The permission should not silently carry over to other repositories or files.

An interactive architecture diagram, for example, may depend on a small amount of client-side JavaScript. Disabling scripts permanently would exclude some of the most useful documents.

Security

I understand that rendering arbitrary repository HTML is different from rendering trusted GitHub UI. In particular, an iframe alone is not a complete security solution.

A possible design could be:

• Render inside a sandboxed iframe. For the static mode, no scripting privileges. For interactive mode, allow-scripts only: do not also grant allow-same-origin, forms, popups, downloads, or top-level navigation.
• Apply a restrictive Content Security Policy to the preview document. Block network connections, submissions, nested frames, and unapproved external resources by default.
• Show a clear indication when interactive mode is enabled and make it easy to turn off.

This is just a suggested model based on my research, not a claim that sandboxing and CSP alone make arbitrary JavaScript completely safe.

Expected experience

For a repository containing:

README.md
README.html
AGENTS.md
src/

I'd like to open the repository and choose between its Markdown README and a rendered HTML README without leaving GitHub. On any .html file, I could select Source or Preview, then deliberately enable interactive JavaScript only if the document requires it.

GitHub Pages remains useful when a project wants to publish a website. This request is different: it is about reviewing a checked-in document in the repository where it lives, including at a particular commit or in a pull request.

Related requests: #109580 (README.html support) and #197070 (static HTML file previews). This proposal builds on both, particularly by asking for an explicit, isolated mode for interactive documents.

[github-actions[bot]]

💬 Your Product Feedback Has Been Submitted 🎉

Thank you for taking the time to share your insights with us! Your feedback is invaluable as we build a better GitHub experience for all our users.

Here's what you can expect moving forward ⏩

• Your input will be carefully reviewed and cataloged by members of our product teams. 
  • Due to the high volume of submissions, we may not always be able to provide individual responses.
  • Rest assured, your feedback will help chart our course for product improvements.
• Other users may engage with your post, sharing their own perspectives or experiences. 
• GitHub staff may reach out for further clarification or insight. 
  • We may 'Answer' your discussion if there is a current solution, workaround, or roadmap/changelog post related to the feedback.

Where to look to see what's shipping 👀

• Read the Changelog for real-time updates on the latest GitHub features, enhancements, and calls for feedback.
• Explore our Product Roadmap, which details upcoming major releases and initiatives.

What you can do in the meantime 💻

• Upvote and comment on other user feedback Discussions that resonate with you.
• Add more information at any point! Useful details include: use cases, relevant labels, desired outcomes, and any accompanying screenshots.

As a member of the GitHub community, your participation is essential. While we can't promise that every suggestion will be implemented, we want to emphasize that your feedback is instrumental in guiding our decisions and priorities.

Thank you once again for your contribution to making GitHub even better! We're grateful for your ongoing support and collaboration in shaping the future of our platform. ⭐