edit

Markdown Syntax

Markdown is a language used by many platforms to specify basic text formatting. This page describes its syntax, with a focus on features that work well within CiviCRM's documentation guide books.

Platform differences

Many platforms which use markdown have expanded or modified the original syntax, which has created subtle differences among various platforms.

Platform-specific markdown references:

The remainder of this page will focus on the markdown syntax which can be used within MkDocs books with the Material theme and common markdown extensions.

CiviCRM markdown coding standards

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

General coding standards

  • 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.

Internal link standards

Note

These standards only apply to internal links and images (which should be internal anyway). There are no markdown standards for external links (which point outside of the current guide).

Valid examples:

  1. [Buildkit](/tools/buildkit.md)
  2. [the API](/api/index.md)
  3. [extension review process](/extensions/lifefycle.md#formal-review)
  4. [section within this page](#that-section)
  5. ![awesome alt text](/images/awesome-screenshot.png)

Rules:

  • Use links which begin with a forward slash. (The root directory is the docs folder.)
    • Exception: when you are linking to a section within the current page, use only the fragment which corresponds to that heading (beginning with #, as in example 4 above.). (Also consider specifying a custom heading ID to prevent broken links if the heading is later renamed.)
  • Append .md when linking to a page.
  • If you are linking to a page which is named index.md, then include index.md in the path (even though your link will technically still work if you don't).
  • If you're linking to a section within a page (other than the current one), then do it as shown in example 3 above (even though some some other variants will also work).
  • Do not use syntax like [Link Text][path] which defines the path in a separate part of the document (even though it will technically work).

Reasons for these internal link standards:

  • Following the rules above helps us avoid broken links.
  • MkDocs will detect broken links when building books, but only if the links are absolute and end with .md.
  • Using consistent syntax helps us to more easily find-and-replace links when moving pages.

Basic inline formatting

Code Result Extension required
*italics* italics
**bold** bold
***bold and italic*** bold and italic
`monospace` monospace
~~strikethrough~~ strikethrough Tilde
==highlight== highlight Mark

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

See the internal link standards above for examples of internal hyperlinks.

Warning

Several different syntax variants will produce functionally identical hyperlinks, but it's important you follow our standards so that we can avoid broken links when re-organizing pages in the future.

A basic external hyperlink in a sentence:

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

If you're using a one external link in many places throughout a page, you can define the URL in one place as follows

See [CRM-1234] for more details.

My favorite issue is [CRM-1234].

[CRM-1234]: https://issues.civicrm.org/jira/browse/CRM-1234

(The third line can be placed anywhere in the file.)

You can also use custom text for a named hyperlink, as shown below:

After learning [how to foo a bar][foobar], then you can party!

[foobar]: https://example.com/foobar

For external links only

Per our standards, named hyperlinks should only be used for external links

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
---------

Custom heading IDs

Extension required

To use custom heading IDs in MkDocs, insert the following code in mkdocs.yml to enable the Attribute Lists extension:

markdown_extensions:
  - markdown.extensions.attr_list

Custom 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.

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.

Lists

Unordered lists

Here is my paragraph (with a blank line after).

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

Note

If you don't include a blank line before your first list item, then the list will become part of the previous element (paragraph, heading, etc).

Alternate syntax:

  • Unordered lists also recognize - and + as item delimiters.
  • Markdown is somewhat flexible with the quantity and position of spaces when making lists.

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 sub-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 than three backticks when necessary to represent code that contains 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, some platforms (e.g. GitHub) will 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:

    • Differ slightly by markdown platform
    • Common language keywords that work on most platforms: bash, css, docker, html, javascript, js, json, markdown, md, perl, php, python, ruby, scss, sh, smarty, sql, xhtml, xml, yaml
    • The Material theme for MkDocs will use the Pygments python library when possible, and in this case provide syntax highlighting for over 300 languages.
  • Syntax highlighting cannot be forced for indented code.

  • Syntax highlighting for inline code is possible with InlineHilite but not recommended.
  • Stack Exchange syntax highlighting is done differently.

Code blocks within lists

Fenced code within lists

Extension required

To use fenced code within lists in MkDocs, install PyMdown Extensions and then insert the following code in mkdocs.yml to enable the Superfences extension:

markdown_extensions:
  - pymdownx.superfences

Then insert fenced code into a list as follows:

*   First item
*   Look at this code:

    ```md
    code
    block
    ```

*   More list items

Indented code within lists

You can use indented code within lists without needing any markdown extensions. Keep a blank line above and below the code and indent the code 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?

Admonitions

Extension required

To use admonitions in MkDocs, insert the following code in mkdocs.yml to enable the Admonitions extension:

markdown_extensions:
  - markdown.extensions.admonition

Syntax

Simple example:

!!! note
    Here is a note for you.

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!

(You can also add an admonition without a title by passing an empty string "" in place of the title.)

Types

The types of admonitions available for use in MkDocs depend on the theme being used. The Material theme supports the following types:

Note

I am a "note" admonition and look the same as "seealso".

Tip

I am a "tip" admonition and look the same as "hint" and "important".

Warning

I am a "warning" admonition and look the same as "attention" and "caution".

Danger

I am a "danger" admonition and look the same as "error".

Summary

I am a "summary" admonition and look the same as "tldr".

Success

I am a "success" admonition and look the same as "check" and "done".

Failure

I am a "failure" admonition and look the same as "fail" and "missing".

Bug

I am a "bug" 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](/directory/image.png)

Note:

  • The image files should be committed into git and stored in the docs/img directory within the project.
  • The path to the image should follow our internal link standards

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.