markdown-it: turn review notes into an HTML reading copy

Your notes contain Markdown headings and a comparison table, but the person reviewing them needs a page they can open. Use markdown-it to convert the text, then package the result as a complete HTML document. The saved reading copy can contain the rendered text and styles without carrying the editor that created it.

The worked example starts with fictional release notes: two completed checks and one unresolved check. A reader can edit the Markdown, see the headings and table update, and download the current rendered result. The download is a reading copy; it does not submit those checks to a release system.

Open the working example · Download the complete HTML

Choose the HTML handling before rendering

For notes supplied as text, start with embedded HTML disabled. That keeps a pasted tag such as <img onerror=...> from becoming an active element. In a browser distribution, construct the parser and render into a dedicated container:

const md = window.markdownit({
  html: false,
  linkify: false,
  typographer: false
});
const input = document.querySelector("#notes");
const preview = document.querySelector("#preview");
function renderNotes() {
  preview.innerHTML = md.render(input.value);
}
input.addEventListener("input", renderNotes);
renderNotes();

The initial call matters. The first preview should show the example notes before the reader types, and it should refresh whenever the source changes.

The markdown-it documentation describes the parser and its configurable rules. Keep plugins and raw HTML out of this small handoff unless you have a concrete need and a corresponding safety review. Disabling HTML is not a promise that arbitrary extensions will be safe.

Know which changes affect the output

A blank line separates paragraphs. A Markdown table needs a header delimiter row. If a pasted table remains plain text, inspect that syntax before changing the page's CSS.

Use the worked source as a practical starting point:

# Release reading copy

Fictional example. Owner and release date: [TO CONFIRM]

| Check | Result |
| --- | --- |
| Keyboard navigation | Complete |
| Narrow-screen layout | Complete |
| Final owner review | Open |

Keep unknown dates and people visibly unresolved. A parser can format an assertion; it cannot supply the evidence behind “Complete.” Replace those example rows with your own recorded checks before using the page at work.

Download the current result

Build a document with a doctype, lang="en", UTF-8 metadata, viewport metadata, a title, and the rendered content. Add the reading styles to that document rather than linking a stylesheet that lives only on your computer.

The example's download contains the reading content and CSS, with no editor JavaScript. This means the recipient gets the state you exported. If you change the Markdown afterward, export a fresh copy; the earlier download does not silently update.

Use the guide's complete HTML download for local exporting. The embedded preview lets you edit and check the text, and directs you to that file when you need a reading-copy download.

Before enabling the download, reject empty or whitespace-only input. A blank editor should show “Enter notes to create a reading copy” and disable the button. After an edit, remove the old “Download prepared” message so it cannot describe a different version of the notes.

If your project already uses Marked, the Marked browser guide covers that separate parser's API and output handling. Do not mix marked.parse() and markdownit().render() in the same instructions.

For review in NOS, use the exported reading copy and keep the Markdown as the authoring original. Ask the reviewer about the unresolved owner check, rather than asking them to infer a release approval from a polished page.