The content for each of these guides is written in [markdown](/markdownrules.md), stored in text files, and hosted in a repository on GitHub. Then, the books are automatically published to **docs.civicrm.org** using our custom [documentation infrastructure](https://github.com/civicrm/civicrm-docs).
The content for each of these books is written in [markdown](/markdownrules.md), stored in text files, and hosted in a repository on GitHub. Then, the books are automatically published to **docs.civicrm.org** using our custom [documentation infrastructure](https://github.com/civicrm/civicrm-docs).
### Languages
...
...
@@ -62,7 +62,7 @@ We welcome contributions, small and large, to documentation!
Before diving into editing, you may find helpful information within the following resources:
-[Markdown syntax](/markdownrules.md) - necessary (but simple) syntax to format content
-[Markdown code standards](/markdownrules.md#standards) - recommendations for markdown syntax to use
-[Style guide](/best-practices/documentation-style-guide.md) - to maintain consistent language and formatting
-[Documentation chat room](https://chat.civicrm.org/civicrm/channels/documentation) - live discussion, fast (most of the time) answers to your questions
-[Documentation mailing list](https://lists.civicrm.org/lists/info/civicrm-docs) - low traffic, mostly used for informational updates regarding documentation projects
...
...
@@ -70,37 +70,43 @@ Before diving into editing, you may find helpful information within the followin
### Submitting issues
The simplest way to help out is to *describe* a change that you think *should* be made by writing a new issue in the issue queue for the guide book you are reading. Then someone will see your issue and act on it, hopefully fast. Each guide book has its own issue queue. First find the GitHub repository for the book (listed in the above table), then when viewing on GitHub, click on "Issues". You will need an account on GitHub to submit a new issue, but creating one is quick and free.
The simplest way to help out is to *describe* a change that you think *should* be made by writing a new issue in the issue queue for the book you are reading. Then someone will see your issue and act on it, hopefully fast. Each book has its own issue queue. First find the GitHub repository for the book (listed in the above table), then when viewing on GitHub, click on "Issues". You will need an account on GitHub to submit a new issue, but creating one is quick and free.
### Editing through GitHub
A slightly more helpful way to plug in is to suggest specific changes by making the changes within the text editor on GitHub. To do this, you would go to the repository, find the markdown file for the page you'd like to change (look at the page's URL in your browser to help figure out where the file is within the repository), then click on the pencil icon at the top right of the page on GitHub. When you make a change, you are essentially forking (i.e. copying) the entire guide into your personal account on GitHub, changing that fork and then requesting to merge your fork into the main guide.
A slightly more helpful way to contribute is to suggest specific changes by making the changes within the text editor on GitHub. To do this, you would go to the repository, find the markdown file for the page you'd like to change (look at the page's URL in your browser to help figure out where the file is within the repository), then click on the pencil icon at the top right of the page on GitHub. When you make a change, you are essentially forking (i.e. copying) the entire book into your personal account on GitHub, changing that fork and then requesting to merge your fork into the main book.
### Editing locally with MkDocs
The most advanced way to work on a guide book is to use git to download all the markdown files to your computer, edit them locally, preview the changes with [MkDocs](http://mkdocs.org/), then use git to push those changes to your personal fork, and finally make a "pull request" on the main repository. This approach makes editing very fast and easy, but does require a bit of setup, and some knowledge of how git works.
The most advanced way to work on a book is to use git to download all the markdown files to your computer, edit them locally, preview the changes with [MkDocs](http://mkdocs.org/), then use git to push those changes to your personal fork, and finally make a "pull request" on the main repository. This approach makes editing very fast and easy, but does require a bit of setup, and some knowledge of how git works.
1. Install MkDocs, plus the [Material theme](http://squidfunk.github.io/mkdocs-material/) and the [Pygments syntax highlighter](http://pygments.org/).
sudo pip install mkdocs
```bash
sudo pip install mkdocs mkdocs-material pygments
```
1. Obtain the source files for the guide you want to edit
1. Obtain the source files for the book you want to edit
1. Find the repository on GitHub *(see "repository" links above, or the "GitHub" link on the bottom left of screen of the documentation you are reading)*
1. Fork the repository on GitHub.
1. Clone *your fork* of the repository to your computer
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.
* Writing CiviCRM [extensions](extend) -- 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](documentation)
* Chatting on [Mattermost](http://chat.civicrm.org)
* Q&A on [Stack Exchange](http://civicrm.stackexchange.com)
[GitHub]:https://github.com
## Platform differences
Markdown language is mostly consistent across these platforms, but some
discrepancies do exist. The `mkdocs` specific guide for markdown, as used in
Many platforms which use markdown have expanded or modified the [original syntax](https://daringfireball.net/projects/markdown/syntax), which has created subtle differences among various platforms.
* Books are built with MkDocs which parses markdown with [Python-Markdown](https://pythonhosted.org/Markdown/).
***But** the extra markdown features available depend heavily on the *theme* and *markdown extensions* used within the book.
*[Material](http://squidfunk.github.io/mkdocs-material/) is the recommended theme to be used for CiviCRM guide books
*[Extensions included within Python-Markdown](https://pythonhosted.org/Markdown/extensions/) can be enabled in the book's `mkdocs.yml` file without installing anything.
*[PyMdown Extensions](http://facelessuser.github.io/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}
...
...
@@ -28,13 +32,16 @@ To maintain some consistency and peace of mind for documentation content editors
Alternate syntax: Underscores for `_italics_` and `__bold__` also work on most
platforms.
...
...
@@ -42,34 +49,51 @@ platforms.
## Hyperlinks
* A basic hyperlink (in a sentence)
### External hyperlinks
A basic external hyperlink in a sentence:
```
Try [CiviCRM](https://civicrm.org) for your database.
```
### Internal hyperlinks
Try [CiviCRM](https://civicrm.org) for your database.
An internal hyperlink on mkdocs. Both of the following syntaxes work because 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)
```
### Named hyperlinks
If you're using a one link in many place throughout a page, you can define the URL in one place as follows
```
See [CRM-1234] for more details.
* An internal hyperlink on mkdocs. The `.md` is optional.
*Make sure to use an absolute path and precede the path with a slash,
After learning [how to foo a bar][foobar], then you can party!
- 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.
[foobar]: https://example.com/foobar
```
## Line breaks and whitespace
**Single line breaks** in markdown code are eliminated in display:
```md
```
This text will all show up
on the
same
...
...
@@ -82,7 +106,7 @@ where possible.
**Double line breaks** create separate paragraphs:
```md
```
This is
one paragraph.
...
...
@@ -108,7 +132,7 @@ 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).
```md
```
Heading 1
=========
...
...
@@ -116,77 +140,66 @@ Heading 2
---------
```
### Heading IDs
### Custom heading IDs
!!! tip "Extension required"
To use custom heading IDs in MkDocs, insert the following code in `mkdocs.yml` to enable the [Attribute Lists](https://pythonhosted.org/Markdown/extensions/attr_list.html) extension:
```yml
markdown_extensions:
- markdown.extensions.attr_list
```
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.
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:
```md
```
## 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 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](https://pythonhosted.org/Markdown/extensions/attr_list.html)
extension:
```yml
markdown_extensions:
-markdown.extensions.attr_list
```
## Lists
### Unordered lists
```md
*My first item is here.
*My second item is here and a
bit longer than the first.
*Then, a third.
```
* 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.
* Unordered lists also recognize `-` and `+` as item delimiters.
* Markdown is somewhat flexible with the quantity and position of spaces when making lists.
### Ordered lists
```md
1.Item
1.Item
1.Item
```
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.
* 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:
List sub-items must be indented 4 spaces:
```md
```
1. Item
1. Item
1. Item
...
...
@@ -204,14 +217,14 @@ List items must be indented 4 spaces:
Use backticks to create inline monospace text:
```md
```
Some `monospace text` amid a paragraph.
```
And if you need to put a backtick inside your monospace text, begin and end
with two backticks:
```md
```
Some ``monospace text with `backticks` inside``, and all amid a paragraph.
```
...
...
@@ -220,15 +233,14 @@ Some ``monospace text with `backticks` inside``, and all amid a paragraph.
A block of **"fenced code"** with three or more backticks on their own line.
````md
````
```
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).*
*Fenced code can use more thank 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.
...
...
@@ -236,7 +248,7 @@ 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:
```md
```
CODE
BLOCK
```
...
...
@@ -244,46 +256,58 @@ A block of **"indented code"** with four spaces at the start of each line:
### 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:
* For code blocks, some platforms (e.g. 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:
* 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](http://pygments.org/docs/lexers).
* Syntax highlighting cannot be forced for indented code.
* Syntax highlighting is not available for inline code.
* Syntax highlighting for inline code is possible with [InlineHilite](http://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/) but not recommended.
*[Stack Exchange syntax highlighting][stack exchange syntax highlighting] is
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:
#### Fenced code within lists
!!! tip "Extension required"
To use fenced code within lists in MkDocs, install [PyMdown Extensions](http://facelessuser.github.io/pymdown-extensions) and then insert the following code in `mkdocs.yml` to enable the [Superfences](http://facelessuser.github.io/pymdown-extensions/extensions/superfences/) extension:
```yml
markdown_extensions:
- pymdownx.superfences
```
Then insert fenced code into a list as follows:
````md
* 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:
```md
* First item
...
...
@@ -305,42 +329,17 @@ above/below and indenting *4 spaces more than your list content*, like this:
* Fun, right?
```
**Fenced code within lists** is shown below. It works on GitHub but **not
mkdocs**:
````md
* 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
!!! tip "Extension required"
To use admonitions in MkDocs, insert the following code in `mkdocs.yml` to enable the [Admonitions](https://pythonhosted.org/Markdown/extensions/admonition.html) extension:
* "hint", "important" (visually identical to "tip")
* "attention", "caution" (visually identical to "warning")
* "error" (visually identical to "danger")
```yml
markdown_extensions:
- markdown.extensions.admonition
```
### Syntax
...
...
@@ -348,7 +347,7 @@ Simple example:
```md
!!! note
This feature is only available as of CiviCRM 4.5.
Here is a note for you.
```
Add a custom title (make sure to quote the title):
...
...
@@ -358,31 +357,52 @@ Add a custom title (make sure to quote the title):
Stand back. I'm about to try science!
```
### Enabling
(You can also add an admonition *without* a title by passing an empty string `""` in place of the title.)
### Types
Admonitions only work in MkDocs when the following code is used to enable
the [Admonition extension](https://pythonhosted.org/Markdown/extensions/admonition.html):
The types of admonitions available for use in MkDocs depend on the theme being used. The Material theme [supports](http://squidfunk.github.io/mkdocs-material/extensions/admonition/#types) 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.
```yml
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.
