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