Skip to content

Fix GitHub README rendering for overview section - #1

Merged
AMDphreak merged 1 commit into
mainfrom
cursor/fix-readme-overview-rendering-de99
Sep 27, 2026
Merged

AMDphreak merged 1 commit into
mainfrom
cursor/fix-readme-overview-rendering-de99

Conversation

@AMDphreak

Copy link
Copy Markdown
Contributor

Problem

On github.com, the README region after the env-github HTML banner through == About The Project rendered 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:

  • No blank line between the closing endif::[] and the overview body
  • Intro paragraph immediately followed by * list markers (list not recognized)
  • Last list item immediately followed by the SLP paragraph (treated as list continuation)

Fix

In README.adoc:

  • Add a blank line after the banner endif::[] block
  • Introduce == Overview so the preamble has a proper section after the banner
  • Add blank lines before the bullet list, after the list, and before the closing link paragraph

Meaning, 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.

Open in Web Open in Cursor 

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>

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.adoc only — 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.adoc for 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.

Open in Web View Automation 

Sent by Cursor Automation: Generate docs

Comment thread README.adoc
link:https://github.com/dev-centr/scriptbook/issues[Request Feature]
endif::[]

== Overview

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@AMDphreak
AMDphreak merged commit 94a9ede into main Sep 27, 2026
3 of 4 checks passed
@AMDphreak
AMDphreak deleted the cursor/fix-readme-overview-rendering-de99 branch September 27, 2026 09:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants