Review a single lesson for AsciiDoc syntax, link formatting, code blocks, slides structure, and question includes. Fixes issues inline and appends a WHY report.
Purpose: Fix AsciiDoc syntax errors, link formatting problems, code block issues, slides structure, and question includes in a single lesson.adoc file. Every change is recorded with a reason.
When to use: Stage 3 of the course review pipeline. Run after grammar and structure reviews.
Input: Path to a lesson folder (e.g. asciidoc/courses/my-course/modules/1-intro/lessons/1-overview/)
Output:
lesson.adoc — fixed in placeREVIEW-REPORT.md in the lesson folder — created or appended with a technical sectionThis review checks and fixes:
Read lesson.adoc in full before making changes. Note:
[.slide blocks (slides-enabled)questions/ subfolder with .adoc filesread:: buttonThere must be a blank line between a paragraph and any list (ordered or unordered).
❌
Here is some text.
* Item 1
* Item 2
✅
Here is some text.
* Item 1
* Item 2
There must be two blank lines between section blocks (before a [.slide] marker or a == header).
❌
[.slide]
== Section One
Content here.
[.slide]
== Section Two
✅
[.slide]
== Section One
Content here.
[.slide]
== Section Two
Replace any markdown that has crept in:
| Markdown (wrong) | AsciiDoc (correct) |
|---|---|
## Heading | == Heading |
**bold** | *bold* |
```lang / ``` | [source,lang]\n----\n---- |
[link text](url) | link:url[link text] |
> blockquote | [quote]\n____\ntext\n____ |
--- (horizontal rule) | ''' |
Use . for ordered list items, not explicit numbers.
❌
1. First step
2. Second step
✅
. First step
. Second step
If an image or code block appears mid-list, use + for continuation:
. First step
+