Fix GitHub README rendering for overview section - #1
Conversation
Add an Overview section and blank lines so paragraphs and bullet lists parse correctly after the env-github banner passthrough block. Co-authored-by: Ryan Johnson <AMDphreak@users.noreply.github.com>
There was a problem hiding this comment.
Documentation review — PR #1
Verdict: Approve the AsciiDoc structure fix. The root-cause analysis matches AsciiDoc block rules on GitHub (env-github HTML banner → preamble needs explicit section breaks and blank lines around lists).
What this PR covers
- Docs updated:
README.adoconly — GitHub-rendered overview (preamble between banner and About The Project). - Codepaths: None; presentation fix for the repo landing page.
- Gaps addressed: Overview bullets and follow-on paragraphs no longer collapse into one blob on github.com.
Follow-ups (separate PR)
- Org README standard also calls for CI and Docs | Dev-Centr badges in the centered header; tracked on branch
cursor/documentation-automation-system-5a13. - After merge, add a one-line note to
changelog.adocfor the GitHub rendering fix (optional but keeps the doc audit trail aligned with functional README changes).
Antora component at docs/ and published pages already describe PlayTime, sidecars, and CLI usage — no Antora edits required for this hunk.
Sent by Cursor Automation: Generate docs
| link:https://github.com/dev-centr/scriptbook/issues[Request Feature] | ||
| endif::[] | ||
|
|
||
| == Overview |
There was a problem hiding this comment.
Using == Overview here is the right fix: it gives GitHub’s AsciiDoc renderer a proper section boundary after the env-github HTML block, and the blank lines correctly separate the intro paragraph, list, and SLP paragraph. No doc-site duplication needed — this mirrors content already in the Antora index.


Problem
On github.com, the README region after the
env-githubHTML banner through== About The Projectrendered as a single messy blob: the intro paragraph, bullet list, and follow-on paragraphs were not separated as proper AsciiDoc blocks.Root cause
The overview content sat directly after
endif::[]with no section heading and without the blank lines AsciiDoc requires to recognize lists and separate paragraphs:endif::[]and the overview body*list markers (list not recognized)Fix
In
README.adoc:endif::[]block== Overviewso the preamble has a proper section after the bannerMeaning, links, and the dual GitHub HTML vs non-GitHub badge pattern are unchanged.
Verification
AsciiDoc list and paragraph rules: lists need a preceding blank line; paragraphs after lists need a separating blank line. The new structure matches those rules so GitHub’s AsciiDoc renderer should show readable paragraphs and bullets through to About The Project.