How can reviewers suggest edits to AsciiDoc files without learning AsciiDoc?
Short answer
Let them work on the rendered page. DraftView shows the AsciiDoc file as formatted text, the reviewer comments and edits it, and DraftView writes the change back as AsciiDoc, not Markdown. It reaches your repository as a normal GitHub Suggested Change.
What the reviewer sees
They see headings, lists, tables, admonitions and code blocks as formatted text. They do not see AsciiDoc markup such as equals signs for headings, asterisks for bold or dashed lines around code. They click into a paragraph and type, or leave a comment on a passage.
What lands in your repository
DraftView turns the edit back into AsciiDoc and maps it to the lines that changed in the source file. On a pull request it arrives as a Suggested Change, so your writers accept it with the usual button.
The file stays AsciiDoc from start to finish. Nothing is converted to another format along the way.
Includes and Antora projects
Real AsciiDoc docs are often built from many files. DraftView shows an include directive as a labeled block with an Edit this file button, so a reviewer can open the included file instead of guessing what it contains.
In the Edit this page flow, DraftView loads included files too, up to 20 per page. It understands Antora resource IDs such as partial$ and example$ when the file sits in a standard modules folder.
File extensions
DraftView treats .adoc, .asciidoc, .ad and .asc files as documentation. Files with other extensions are ignored.
What to know before you rely on this
- Advanced AsciiDoc features, such as macros and heavy conditional logic, may show as locked blocks instead of editable text.
- Review the suggested change before you accept it, especially if the file uses unusual syntax.
- Reviewers without GitHub need a teammate to push their suggestions to the pull request.
- DraftView is for review and small edits. It does not build or publish your docs site.
Common questions
- Does DraftView convert AsciiDoc to Markdown?
- No. An AsciiDoc file is saved back as AsciiDoc.
- Can a reviewer edit text inside an included file?
- Yes. They open it from the Edit this file button on the include block.
- Is there a way to just preview AsciiDoc?
- Yes. AsciiDoc Alive is a free online AsciiDoc editor with live preview, linked below.
Keep reading
Last updated 2026-10-17