markdown.md

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:

• Mattermost markdown
• Stack Exchange markdown
• GitHub markdown
• CiviCRM's guide book markdown:
  • Books are built with MkDocs which parses markdown with Python-Markdown.
  • But the extra markdown features available depend heavily on the theme and markdown extensions used within the book.
  • Material is the recommended theme to be used for CiviCRM guide books
  • Extensions included within Python-Markdown can be enabled in the book's mkdocs.yml file without installing anything.
  • PyMdown Extensions is a 3rd party package that provides many additionally useful extensions.

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

General code standards {:#general-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 URL standards {:#internal-url-standards}

!!! note These standards only apply to internal hyperlinks 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 absolute URLs 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 URL (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][url] which defines the URL in a separate part of the document (even though it will technically work).

Reasons for these internal URL 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.

Internal hyperlinks

See the internal URL 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.

External hyperlinks

A basic external hyperlink in a sentence:

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

Named hyperlinks

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