Reviewing Markdown Files¶
When writing documentation using the Markdown format, we often care much less about the source file than the resulting rich text document. Attaching a Markdown file (.md) to a review request will enable a special review UI that will render the document.
To begin reviewing a Markdown file, click the thumbnail or the “Review” link for the file attachment on the review request page.
The Markdown Review interface presents two tabs: Rendered and Source. These let you switch between the rendered HTML and the plain-text source, respectively. Comments can be added in either view.
Reading Existing Comments¶
The Markdown review UI will show blue comment flags along the left-hand side of the document. The number inside the comment flag indicates how many comments were made on that block.
If you move the mouse cursor over the comment flag, a tooltip will appear showing a summary of the comments made.
If you click on the block or the comment flag, the comment dialog will appear, along with a blue side panel on the left showing those existing comments. You can still write new comments in the green area of the comment box.
It’s important to note that this is not the place to reply to those comments. When you add a comment from the diff viewer, it’s creating a new top-level review (akin to a new thread). If you want to reply to existing comments, you can do so from the Reviews page. The Reply link here is a shortcut to jump directly to the relevant comment on the Reviews page.
The view here is meant to be used only as a reference to see if other people have already said what you plan to say.
Viewing Other Markdown Revisions¶
New in version 2.5.
As explained in Reviewing File Attachments, you can view and compare revisions of a markdown file attachment. When viewing interdiffs, Review Board will display the two file revisions side by side. Changing from Rendered and Source will change both revisions at the same time.