Projects: promote the README to a first-class Markdown view (and allow more than one)

[ronniegeraghty]

🏷️ Discussion Type

Product Feedback

💬 Feature/Topic Area

Projects

Body

What already exists

Projects already render Markdown. The project README supports full Markdown —
headers, images, links, lists — and it works well. This isn't a request for a new
rendering engine.

The gap is where it lives and how many you get.

1. It's hidden. The README is reachable only via a small icon in the top-right
   toolbar (or ⋯ → Settings). It isn't in the view bar, which is where people
   actually navigate a project. In practice most collaborators never open it —
   several people on my own team didn't know it existed.
2. There's exactly one. A single project-level README forces every piece of
   narrative content into one document. Real teams want several targeted ones:
   "How to use this board", "Definition of done", "Triage rotation", "Q3 goals",
   "Links to specs and dashboards."

Proposal

Make a Markdown document a view, alongside Table / Board / Roadmap:

• Add Markdown (or Document) as a fourth layout in the view picker.
• These views appear as named tabs in the view bar — the place people already look.
• The existing project README becomes the default instance, so nothing is lost and
  every existing project gets an immediate discoverability win.
• Allow multiple such views, independently named, ordered, and permissioned with
  the project.
• Inherit standard GitHub Markdown: issue autolinks, task lists, mermaid, alerts.

Why this matters

The board is the team's landing page, but the "how this works" context lives
somewhere else — a wiki, Notion, a Loop page — because the README isn't visible
enough to be trusted as the canonical spot. Surfacing it as a tab, and allowing
more than one, keeps the narrative next to the work instead of one link away.

This would unblock a cluster of long-standing asks

Searching this category turns up a recurring theme going back to the Projects Beta.
Notably, the first half of it already shipped — GitHub confirmed as much in
#8040 pointing at the
2022-02-02 update, which delivered the description/README. What was never addressed
is placement and multiplicity, and that's exactly what these threads keep circling
back to:

• #16329 — Projects beta doesn't show the README or overall description at the top of the project board
  Still open, still true four years later. A Markdown view solves this directly.
• #6429 — [Projects Beta] Adding a View description section (↑10)
  A Markdown view is a superset: instead of a fixed blurb slot per view, you get a
  full document you can place anywhere in the view bar, including right next to the
  view it describes.
• #12683 — Github Projects: Full view option with description on board option
  Same shape.
• #11600 — Provide capability to pin project description
  and #11601 — Show project description under project title
  Both are workarounds for the description not being somewhere prominent. A tab
  makes pinning moot.
• #5834 — Projects beta feedback: we'd love a project-wide "description" field! (↑11)
  and #8040 — Projects - Description (↑12)
  The original "we want a description" asks.

None of these are literally asking for a Markdown view, and this proposal doesn't
match any of them exactly. But I'd argue it gives each of them a better answer than
the one they asked for: rather than adding one more fixed-purpose text slot per
surface, it gives people a general-purpose document primitive they can shape to
whatever their team actually needs. One feature, several long-tail requests retired.

Smaller win, if the full layout is too big

Even just surfacing the existing README as a tab in the view bar — no new layout,
no multiple docs — would solve most of the discoverability problem and close out
#16329 on its own. That seems
like a very cheap change relative to how much of this thread history it resolves.

Guidelines

• I have read the above statement and can confirm my post is relevant to the GitHub feature areas Issues and/or Projects.

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