Markdown as we use it

Pages here are written in Markdown, the plain-text format where # Title makes a heading and - item makes a bullet. We follow CommonMark, the standard version of Markdown, and add a few things of our own. Together this is called NGDP-Compatible Markdown, or NCM.

This page is the reference for how to write a page. It has two parts:

• What works: everything standard Markdown allows, plus our additions.
• How we write it: the style we use on our own pages. Please follow it on yours, so pages look the same everywhere.

What works

Standard Markdown

All of it: headings, paragraphs, bold and italic, links, images, quotes, lists, code, horizontal lines, and some HTML.

Our additions

• Line breaks: a new line in what you type is a new line on the page. To break a line without starting a new one in the editor, type \\. Typing <br> is refused when you save. See Markdown Cheat Sheet.
• Tables: || Header || Header || then | cell | cell | rows. See Table Examples and JSPWiki Table Functionality.
• Strikethrough: ~~text~~.
• Subscript and superscript: H~2~O and X^2^, with no spaces between the marks. For longer text use %%sub text/% and %%sup text/%.
• Footnotes: a claim[^1] in the text and [^1]: the note on its own line. See Using FootnotesPlugin.
• Emoji: :smile: and other shortcodes. See Using Emoji.
• Links to pages: [Page Name], or [Text to show|Page Name]. Link to a heading on a page with [Text|Page Name#section=Heading Text]. See Using Links.
• Plugins: [{PluginName param='value'}] inserts live content, such as a list of recent changes. See Plugin.
• Variables: [{$pagename}] inserts the page's name; there are many others. See System Variables.
• Boxes and styling: %%information … /% makes an information box; %%(color:red) text/% styles a few words. See Page Content.

Good to know

• foo_bar_baz stays as written. Underscores inside a word never make italics; use *italic*.
• Anything inside code, `like this` or a code block, is shown exactly as typed. Plugins, links and variables inside code don't run.
• Headings can be linked to. A heading that appears twice on a page gets -1 added for the second one, so link to the first.

Doesn't work

• Checkboxes (- [ ], - [x]): the brackets are read as a page link.
• Definition lists, ==highlight==, and {#my-id} after a heading: these show as plain text.
• Old JSPWiki formatting, !!! headings and * / ** / # at the start of a line: converted when a page is imported, not when it is shown or saved. Saving keeps exactly what you typed. A page that still has old formatting can be fixed with the Convert to NCM admin tool.

How we write it

• Headings: # for the page title, ## for sections, ### below that, each followed by a space.
• Bold and italic: __bold__ and *italic*.
• Bullets: a hyphen and a space, - item. Don't use * or +; switching between them in the middle of a list starts a new list.
• Bullets under bullets: indent 2 spaces for each level.
• Numbered steps: a bullet with the number and no dot: - 1 First step, - 2 Second step.
• Links: [Page Name] or [Text|Page Name] for pages here, and [Text|https://example.com] for other sites.
• Tables: || Header || and | cell | rows.
• Code: three backticks and the language, then the code, then three backticks:

```bash
./server.sh status
```

• Dividing lines: --- on its own line, with a blank line above it. Without the blank line, the text above turns into a heading.
• Quotes: > at the start of each line. A blank line between two groups makes two separate quotes.
• HTML boxes: put <div …> and </div> on lines of their own, with a blank line above and below the text inside, so the formatting inside works.
• A bullet that starts with > (such as - \>10 mg): put a backslash before the >, or it turns into a quote.

More help

• Markdown Cheat Sheet: quick examples of each element
• Using Links: every kind of link
• Table Examples: tables, with styling
• Page Content: boxes, styles and plugins on a page
• Editing a Page: the editor itself