Text editing guides

Turn a plain-text release note into Markdown

·

A plain-text release note can use uppercase titles, labels with a colon and bullet glyphs. Turn those cues into Markdown so the hierarchy stays visible when the note reaches your team wiki.

Text to Markdown

Format the release note and check the heading levels

Select Load example with the default rules. RELEASE NOTES becomes a level-two heading with two hash marks. Follow-up: and Checklist: each become a level-three heading with three hash marks and no colon.

The round bullets become hyphens. The export step starts with 1. in the result. Check that café, خريطة and the joined emoji are still present in the two list items.

CommonMark 0.31.2 — ATX headingsCommonMark 0.31.2 — list items

Scroll to the last line. Find the closing angle bracket immediately before the period. The URL should end in /guide. Switch off Bare HTTP and HTTPS links to keep that line as typed.

Switch on Bold uppercase words. The API acronym in the second checklist item acquires two asterisks on each side. Turn off Uppercase headings if the all-caps opening is a notice rather than the title.

CommonMark 0.31.2 — autolinks

Open the saved note in a Markdown renderer

Download Markdown and read the resulting file in the destination editor. Check that the bullets and ordered steps render as two separate lists. The line of equals signs becomes three asterisks, which CommonMark uses for a horizontal rule.

For a release note with existing fenced code, keep the opening and closing fence around the sample. The converter leaves the text inside it alone, including all-caps lines.

CommonMark 0.31.2 — thematic breaks

Common questions

What happens to an Arabic line used as a heading?

Arabic has no uppercase and lowercase distinction. You can end a short Arabic label with a colon to use the section label rule.

Why is the colon gone from the section heading?

The trailing colon identifies the section label. The level-three Markdown marker takes over that role.

Sources

Put it into practice.

Related guides