Repository navigation
breaking change: verify READMEs in markdown mode, not gfm - #3
Merged
Merged
Conversation
Every rendering rule in §7.1 was found by rendering through `gh api /markdown` — under `mode: "gfm"`, which is comment semantics, not README semantics. The two disagree about the one thing those rules are mostly about: under gfm every single newline becomes a `<br>` and no heading anchors are emitted; under `mode: "markdown"` newlines inside a paragraph join and headings carry the anchors that in-page links need. One file measured 116 `<br>` outside code under gfm and zero under markdown. Verifying a README under gfm shows a page no reader will see, and hides exactly the line-collapse the couplet rule exists for. The couplet rule survives — it is true under the correct mode. "All badges on one source line" does not: paragraph lines join on their own, so it described the verification artefact rather than the page. What remains is the part that was always real, that every badge is a link.
There was a problem hiding this comment.
Pull request overview
Updates the documentation standards to clarify that README rendering rules must be verified using the same rendering mode GitHub uses for READMEs, and removes a previously stated “single source line” constraint for badge rows that was an artifact of the prior verification method.
Changes:
- Clarifies the README rendering verification approach and explains the observed differences between
/markdownAPI modes. - Removes “all badges on one source line” from skeletons/checklists, keeping the “every badge is a link” requirement.
- Updates the TR mirror to match the English standards changes.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| STANDARDS.tr.md | Updates the Turkish standards text to clarify README rendering verification mode and implications. |
| STANDARDS.md | Updates the English standards text to clarify README rendering verification mode and implications. |
| project-type/TOOL.md | Adjusts tool README skeleton badge-row placeholder to remove “one source line” requirement. |
| overlay/PUBLISHED-VERDICT.md | Updates overlay skeleton and checklist to remove “one source line” badge-row requirement and explain paragraph joining. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+243
to
+251
| **Render it the way a README is rendered.** `gh api /markdown` takes a | ||
| `mode`, and the two modes disagree about the thing most of these rules | ||
| are about. `mode: "gfm"` is *comment* semantics: every single newline | ||
| becomes a `<br>`, and no heading anchors are emitted. `mode: "markdown"` | ||
| is what a README gets: newlines inside a paragraph join, and headings | ||
| carry the anchors that in-page links depend on. *Measured on one file: | ||
| 116 `<br>` outside code under gfm, zero under markdown.* Verifying a | ||
| README under gfm shows you a page no reader will see — and it hides | ||
| exactly the line-collapse the next rule is about. |
Comment on lines
+247
to
+255
| **README nasıl render ediliyorsa öyle render et.** `gh api /markdown` | ||
| bir `mode` alıyor ve iki mod, bu kuralların asıl konusunda birbirine | ||
| zıt. `mode: "gfm"` YORUM semantiğidir: her tek satır sonu `<br>` olur ve | ||
| başlık çapası hiç üretilmez. `mode: "markdown"` README'nin aldığıdır: | ||
| paragraf içindeki satırlar birleşir, başlıklar sayfa-içi linklerin | ||
| dayandığı çapaları taşır. *Tek dosyada ölçüldü: gfm'de kod dışında 116 | ||
| `<br>`, markdown'da sıfır.* README'yi gfm ile doğrulamak, hiçbir okurun | ||
| görmeyeceği bir sayfaya bakmaktır — üstelik bir sonraki kuralın konusu | ||
| olan satır-çökmesini tam da gizler. |
Comment on lines
+70
to
+71
| [badge row — EVERY badge linked; source lines may be separate, | ||
| they join in a paragraph] |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Every rendering rule in §7.1 was found by rendering through
gh api /markdown— undermode: "gfm". That is comment semantics,not README semantics, and the two disagree about the one thing those
rules are mostly about.
Under
gfm, every single newline becomes a<br>and no headinganchors are emitted. Under
mode: "markdown", newlines inside aparagraph join and headings carry the anchors that in-page links
depend on. Measured on one README: 116
<br>outside code undergfm, zero under markdown.
So the verification method itself has to be stated, and it now is.
What survives. The couplet rule — two blockquote lines in one
paragraph collapse into one, use a trailing
<br>— is true underthe correct mode. So is everything else in the block.
What does not. "All badges on one source line" described the
verification artefact, not the page: paragraph lines join on their
own, and a badge row written across six source lines renders inline.
The part that was always real is that every badge is a link, and that
is what remains. Dropped from the overlay skeleton, its checklist, and
the tool skeleton.
TR mirror updated.