markdownrules.md

Markdown Syntax

Learning Markdown language is useful for:

• Writing CiviCRM extensions -- In order for your extension to be compliant, you must provide extension documentation, written in markdown.
• Writing other .md files that display on GitHub
• Contributing to CiviCRM documentation
• Chatting on Mattermost
• Q&A on Stack Exchange

Markdown language is mostly consistent across these platforms, but some discrepancies do exist. The mkdocs specific guide for markdown, as used in this book is here.

CiviCRM markdown code standards {:#standards}

To maintain some consistency and peace of mind for documentation content editors, we've agreed to recommend the following syntax as markdown code standards. These are not hard rules though.

• Line length: write long lines (i.e. one line per paragraph) and set your text editor to view them with a "soft wrap".
• Ordered lists: use 1. as delimiters.
• Unordered lists: use * to delimiters.
• Headings: use hashes like ## Heading 2.

Basics

• *italics*
• **bold**
• ***bold and italic***
• ~~strikethrough~~ (GitHub/Mattermost/StackExchange)
• <del>strikethrough</del> (mkdocs)

Alternate syntax: Underscores for _italics_ and __bold__ also work on most platforms.

Hyperlinks

• A basic hyperlink (in a sentence)

  Try [CiviCRM](https://civicrm.org) for your database.

• An internal hyperlink on mkdocs. The .md is optional. Make sure to use an absolute path and precede the path with a slash, as shown below.

  [extensions](/extensions/basics)
  [extensions](/extensions/basics.md)

• With long URLs, the following syntax is better.

  See [this issue][CRM-19799] for more details.
  
  [CRM-19799]: https://issues.civicrm.org/jira/browse/CRM-19799

  • The second line can be placed anywhere in the file.
  • Optionally, if the link ID ("CRM-19799" in this case) is omitted, you can use the link text ("this issue") to reference the link in the second line.

Line breaks and whitespace

Single line breaks in markdown code are eliminated in display:

This text will all show up
on the
same
line.

This makes it easy to avoid very long lines in markdown code. As a rule of thumb, keep your markdown code free of lines longer than 80 characters where possible.

Double line breaks create separate paragraphs:

This is
one paragraph.

This is a second.

Headings

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

The above syntax is called "ATX style headers" in markdown terminology, and is the preferred syntax within the CiviCRM community. An alternate syntax called "setext style headers" works for h1 and h2 as follows (but please avoid creating new content with this syntax).

Heading 1
=========

Heading 2
---------

Heading IDs

Heading IDs allow you to link to specific sections in a page by appending the heading ID to the page URL. Most markdown platforms (e.g. MkDocs, GitHub) automatically set a heading ID for every heading and do so using the text of the heading itself. Sticking with the default is great is most cases, however sometimes you want to override it. Some markdown platforms (e.g. MkDocs) allow you to set custom heading IDs to override the automatically chosen value.

Setting a custom ID:

## How to foo a bar {:#foo}

This is helpful when you think that readers are likely to frequently link to this section in the future.

• Custom heading IDs will remain the same (thus preserving incoming links) even after the text of the heading is edited.
• Custom heading IDs create shorter URLs.

Custom heading IDs only work in MkDocs when the following code is used to enable the Attribute Lists extension:

markdown_extensions:
  - markdown.extensions.attr_list

Lists

Unordered lists

*   My first item is here.
*   My second item is here and a
    bit longer than the first.
*   Then, a third.

Alternate syntax:

• Unordered lists also recognize - and + as item delimiters.
• Markdown is somewhat flexible with the quantity and position of spaces when making lists, but using 3 spaces after the dash means that sub-lists look nicer in code.

Ordered lists

1.  Item
1.  Item
1.  Item

Alternate syntax:

• Ordered lists items are automatically re-numbered sequentially upon display which means all items can begin with 1, or they can be ordered sequentially in code.

Nested lists

List items must be indented 4 spaces:

1.  Item
    1.  Item
    1.  Item
1.  Item
    * Item
    * Item
    * Item
1. Item

Code

Inline code

Use backticks to create inline monospace text:

Some `monospace text` amid a paragraph.

And if you need to put a backtick inside your monospace text, begin and end with two backticks:

Some ``monospace text with `backticks` inside``, and all amid a paragraph.

Code blocks

A block of "fenced code" with three or more backticks on their own line.

```
CODE
BLOCK
```

Fenced code can use more backticks when necessary to represent code with 3 backticks (which is what you'd see in the source for this page).

Alternate syntax: For fenced code, the tilde ~ character also works in place of the backtick character but should be avoided for consistency.

A block of "indented code" with four spaces at the start of each line:

    CODE
    BLOCK

Syntax highlighting for code

• For code blocks, most platforms (e.g. mkdocs, GitHub) will guess guess the language of the code and automatically apply syntax highlighting to the display.

• To force a particular type of syntax highlighting, use fenced code with a keyword (like javascript in this case) as follows:

  ```javascript
  var cj = CRM.$ = jQuery;
  ```

• Available language keywords for forced syntax highlighting differ slightly by markdown platform, but here are some common ones: as, atom, bas, bash, boot, c, c++, cake, cc, cjsx, cl2, clj, cljc, cljs, cljsc, cljs.hl, cljx, clojure, coffee, _coffee, coffeescript, cpp, cs, csharp, cson, css, d, dart, delphi, dfm, di, diff, django, docker, dockerfile, dpr, erl, erlang, f90, f95, freepascal, fs, fsharp, gcode, gemspec, go, groovy, gyp, h, h++, handlebars, haskell, haxe, hbs, hic, hpp, hs, html, html.handlebars, html.hbs, hx, iced, irb, java, javascript, jinja, jl, js, json, jsp, jsx, julia, kotlin, kt, ktm, kts, lazarus, less, lfm, lisp, lpr, lua, m, mak, makefile, markdown, matlab, md, mk, mkd, mkdown, ml, mm, nc, objc, obj-c, objectivec, ocaml, osascript, pas, pascal, perl, php, pl, plist, podspec, powershell, pp, ps, ps1, puppet, py, python, r, rb, rs, rss, ruby, rust, scala, scheme, scm, scpt, scss, sh, sld, smalltalk, sql, st, swift, tex, thor, v, vb, vbnet, vbs, vbscript, veo, xhtml, xml, xsl, yaml, zsh

• Syntax highlighting cannot be forced for indented code.

• Syntax highlighting is not available for inline code.

• Stack Exchange syntax highlighting is done differently.

Code blocks within lists

You can use indented code within lists by keeping a blank line above/below and indenting 4 spaces more than your list content, like this:

*   First item
*   Look at this code:

        CODE BLOCK WITHIN
        TOP LEVEL LIST ITEM

*   More list items
*   A nested list is here:
    1.  Alpha
    1.  Beta, with some code

            CODE BLOCK WITHIN
            SUB-LIST ITEM

    1. Gamma

*   Fun, right?

Fenced code within lists is shown below. It works on GitHub but not mkdocs:

*   First item
*   Look at this code:

    ```md
    code
    block
    ```

*   More list items

Admonitions

Types

!!! note I am a "note" admonition.

!!! tip I am a "tip" admonition.

!!! warning I am a "warning" admonition.

!!! danger I am a "danger" admonition.

Other types

• "hint", "important" (visually identical to "tip")
• "attention", "caution" (visually identical to "warning")
• "error" (visually identical to "danger")

Syntax

Simple example:

!!! note
    This feature is only available as of CiviCRM 4.5.

Add a custom title (make sure to quote the title):

!!! danger "Don't try this at home!"
    Stand back. I'm about to try science!

Enabling

Admonitions only work in MkDocs when the following code is used to enable the Admonition extension:

markdown_extensions:
  - markdown.extensions.admonition

Images

Images function mostly the same as hyperlinks, but preceded by an exclamation point and with alt text in place of the link text.

![Alt text](image.png)

or

![Alt text][id]

[id]: image.png

Other markdown syntax

• Tables (to be avoided when possible)

• Emojis (great for Mattermost)

• Blockquotes

  > This text is a blockquote, typically used
  > to represent prose written by a person. It
  > will be displayed slightly indented.

External references

• Mattermost markdown
• Stack Exchange markdown
• GitHub markdown
• Official markdown reference (though somewhat difficult to read)