Enhancing GitHub's Community Health: Why AsciiDoc Recognition Boosts Your Repository's Software KPI Dashboard
GitHub repositories often strive for a complete "Community Profile" checklist, a vital indicator of project health and maintainability. This checklist, visible on a repository's Insights page, acts as a rudimentary software kpi dashboard for community engagement and best practices. However, a recent discussion highlights a significant oversight: the platform’s community standards tab currently only recognizes Markdown (.md) files for crucial health indicators like CONTRIBUTING, CODE_OF_CONDUCT, and SECURITY.
The AsciiDoc Dilemma: Missing from the Community Health Score
The core of the issue, as raised by user hyperpolymath in Discussion #189645, is that repositories utilizing AsciiDoc (.adoc) are unfairly penalized in their community health score. Despite GitHub's excellent native rendering support for AsciiDoc files—meaning README.adoc displays perfectly in the repository view—the platform's community health checklist fails to detect their .adoc equivalents. This creates an unnecessary hurdle for projects committed to AsciiDoc.
Why AsciiDoc Recognition Matters for Project Health
AsciiDoc is not merely an alternative; it's a powerful markup language widely adopted in enterprise, documentation-heavy, and standards-oriented projects. Its richer feature set, including robust includes, cross-references, conditional content, and callouts, makes it the preferred choice for major ecosystems like Fedora, Spring, the Asciidoctor project itself, and various Eclipse Foundation initiatives. Forcing these projects to maintain duplicate .md files solely for GitHub's community health checklist introduces significant friction and redundant effort.
As notcoderhuman eloquently put it in a supporting reply, this is "exactly the kind of small-but-impactful improvement the AsciiDoc community has been waiting for." The current situation means that even a meticulously documented project using CONTRIBUTING.adoc or SECURITY.adoc will appear incomplete on its software kpi dashboard within GitHub's Insights, simply because the file extension isn't recognized.
The Ask: Extend Recognition to .adoc Files
The feature request is straightforward: extend the community health file detection to include .adoc alongside .md for:
CONTRIBUTING.adocCODE_OF_CONDUCT.adocREADME.adoc(already renders, but not always for health checks)SECURITY.adocSUPPORT.adoc
This change would be a "tiny backend change with huge benefit," as GitHub already possesses the underlying Asciidoctor engine to parse and render these files. The logic for health files is already flexible enough to handle .md, extensionless files, and .txt, making the addition of .adoc a logical and consistent enhancement.
Current Workarounds (and why they're not ideal)
Until this feature is implemented, projects are left with two unappealing options:
- Maintain both
.mdand.adocversions of the same critical community health files, leading to duplication and potential synchronization issues. - Accept an incomplete community health score, which misrepresents the project's adherence to best practices and negatively impacts its perceived health on the software kpi dashboard.
Recognizing .adoc files would not only remove unnecessary friction for thousands of repositories but also provide a more accurate and comprehensive view of project health on GitHub, truly reflecting a repository's commitment to community standards and improving the overall developer experience.
