Markup Converter

What it's for

Move text between the three markup languages most documentation is written in, without retyping it. HTML is what web pages are made of, Markdown is what README files, GitHub and many note apps use, and AsciiDoc is a richer plain-text format used for books and technical documentation. Plain text is words with no markup at all.

For example, when you’re moving a project’s docs from Markdown to AsciiDoc, or want a web page’s text as Markdown for your notes, or need a README’s words without the # and ** marks.

How to use it

Choose the format you have under From and the one you want under To, then type or paste. The result updates as you type. Swap turns the result into the new source, so you can convert back and check what survived. Both choices are remembered in this browser.

Headings, bold, italic, code, links, images, lists (including nested lists and task lists), quotes, code blocks with their language, and tables all carry across. AsciiDoc’s notes and warnings (NOTE:, TIP: and so on) become quotes in Markdown, and its description lists become a bold term with its description below.

As plain text, paragraphs are separated by a blank line, list items start with - or a number, nested lists are indented, table cells are separated by tabs, and a link’s address follows its text in brackets. Plain text read in becomes one paragraph per blank-line-separated block, with single line breaks kept.

Example

With From set to HTML and To set to Markdown, paste:

<h2>Shopping</h2>
<p>Buy <strong>milk</strong> and <a href="https://example.com/shop">bread</a>.</p>
<ul><li>Apples</li><li>Pears</li></ul>

The result is:

## Shopping

Buy **milk** and [bread](https://example.com/shop).

- Apples
- Pears

Change To to AsciiDoc and it becomes == Shopping, Buy *milk* and https://example.com/shop[bread]. and a list of * Apples and * Pears. Change it to Plain text and the link’s address moves into brackets: Buy milk and bread (https://example.com/shop).

Good to know

Everything passes through HTML on the way, so anything the target format has no way to write is simplified or dropped: Markdown has no underline, admonitions or description lists, and HTML’s colours, classes and layout don’t survive in Markdown or AsciiDoc. Plain text keeps only the words, so headings, bold and quotes are lost, and a code block’s language is dropped. Markdown joins lines that have no blank line between them, so they run together in plain text, as they do on a web page. A Markdown table needs a header row, so a table without one stays as HTML. AsciiDoc include:: lines become a link to the file, since nothing is read from outside the page. Text that happens to contain AsciiDoc marks, such as a pair of * or #, isn’t escaped and may turn into formatting.