Using Markdown in PainChek

We use the Markdown syntax to format text in the PainChek application, including:

a) User consent items such as our Privacy Policy and our terms and conditions

b) FAQ items, including the "About PainChek and Dementia" details

What is Markdown

Markdown is a a plain text format for writing structured documents, based on formatting conventions from email and usenet.

It was developed in 2004 by John Gruber, who wrote the first markdown-to-html converter in Perl, and it soon became widely used in websites. By 2014 there were dozens of implementations in many languages.

However, John Gruber’s canonical description of Markdown’s syntax does not specify the syntax unambiguously.  In the absence of a spec, early implementers consulted the original Markdown.pl code to resolve these ambiguities. But Markdown.pl was quite buggy, and gave manifestly bad results in many cases, so it was not a satisfactory replacement for a spec. Markdown.pl was last updated December 17th, 2004.

Commonmark is a standard, unambiguous syntax specification for Markdown, along with a suite of comprehensive tests to validate Markdown implementations against this specification.

The commonmark syntax is the format used by PainChek.

Online Tools

You can use https://spec.commonmark.org/dingus/ to display a formatted version of the text.

There are numerous other tools available - e.g. https://dillinger.io/ and http://markdownlivepreview.com/ - but the one above is preferred as it adheres to the commonmark spec (https://commonmark.org/).

Converting from Word or Confluence to Markdown

The recommended process is:

a) Copy the text from the Confluence page into the clipboard

b) Paste the text into https://euangoddard.github.io/clipboard2markdown/


You will need to manually tidy up the resulting markdown, including:

ItemWhat to doExample pre tidy-upExample post tidy-up
Update Level 1 headingsRemove escape character (\), prefix with three hashes (###), remove underline (==============)1\. Background
==============
### 1. Background
Update Level 3 headingsRemove escape character (\)### 1\. Background### 1. Background
Fixed second level numbered lists

Replace number & full stop, a letter and a bracket. 

Ensure the line is intended with 2 spaces and there is a single space after the bracket.

Ensure the proceeding line (including the first level item that the second level items belong to - the "8. You must ... an assessment:" line in this example) is terminated with two spaces.

8. You must allow the App to access the camera of your Smart Device which will be used to conduct an analysis of the Patient's face as one of the domains of the pain assessment. The video footage obtained during an assessment:
  1. is processed on the Smart Device;
  2. never leaves the Smart Device; and
  3. is discarded as soon as the facial analysis is completed;
8. You must allow the App to access the camera of your Smart Device which will be used to conduct an analysis of the Patient's face as one of the domains of the pain assessment. The video footage obtained during an assessment:  
  a) is processed on the Smart Device;  
  b) never leaves the Smart Device; and  
  c) is discarded as soon as the facial analysis is completed;
Restore bold entriesSurround text with 2 asterisks (**)4. The Pain Assessment is made available through the App and is subject to the following Terms and Conditions, as amended from time to time (Terms and Conditions).4. The Pain Assessment is made available through the App and is subject to the following Terms and Conditions, as amended from time to time (**Terms and Conditions**).
Insert blank linesAdd a backslash (\) on a line by itself in order to add an additional blank paragraph.

1. These Terms and Conditions are governed by and construed in accordance with the laws of New South Wales, Australia without regard to its conflict of law rules, and the courts of New South Wales, Australia shall have exclusive jurisdiction over any dispute that may arise between you and us in relation to these Terms and Conditions or the App.

_This policy was last updated on 18th September 2018._

1. These Terms and Conditions are governed by and construed in accordance with the laws of New South Wales, Australia without regard to its conflict of law rules, and the courts of New South Wales, Australia shall have exclusive jurisdiction over any dispute that may arise between you and us in relation to these Terms and Conditions or the App.

\
\
_This policy was last updated on 18th September 2018._


Sample Markdown

Raw MarkdownFormatted Markdown (http://markdownlivepreview.com/)Formatted Markdown (Render Markdown Confluence macro)

### 1. Purpose of our Privacy Policy

1. PainChek Ltd ABN 21 146 035 127 (**we** , **us** or **our**) provides the PainChek web & mobile system (**PainChek**), which is intended to allow users to access parts of a Patient's account to:
a) Assess and record the Patient's level of pain and the pain relief administered to manage their pain over time
b) Connect and share information with other authorised users
c) Access such other information and features, as we may make available via PainChek from time-to-time in accordance with the PainChek Terms of Service.

In order to achieve the above, Users have to create, store and edit Personal Information about Patients and Users.

2. Care-Receivers being assessed for pain shall be collectively referred to as **Patients** throughout this Privacy Policy.

3. Patients, Care-Givers and the organisations responsible for caring for Patients shall be collectively referred to as **Users** throughout this Privacy Policy.

(info) Note: Each implementation of Markdown will result in slightly different appearances - these are OK and we should not get hung up on the minor differences

Displaying Markdown in Confluence

We use the Render Markdown free plugin in Confluence to allow markdown to be captured.  In edit mode, the macro contains the raw Markdown (which we can cut & paste into the PainChek database) and when the page is displayed, the formatted markdown is displayed.

Commonly Used Markdown Formats

This section documents a few key markdown features that we commonly use in the PainChek markdown text.

Markdown is plan text, but uses a number of special syntaxes to enable the rendered markdown to look nice whilst maintaining the readability of the raw markdown.

ItemDescriptionRaw Markdown Raw Markdown (with spaces indicated by a hyphen)Rendered MarkdownComment
Bold TextBold textThis is **bold** text.n/a


Multiple lines of text

Multiple lines of text (separated by a carriage return) are deemed to be a single line in a paragraph.

This is a sentence. This is the second sentence (which has wrapped) if the line is long enough.
This is the second sentence.

n/a

If the line does not end with a space, a space is added when the lines are concatenated.

If a line ends with 2 spaces, it's treated as a line break (see the "Line breaks" section below).

Multiple lines of text issues

Some engines render multiple lines  (separated by a carriage return) as a two lines (i.e. it assumes there is a line break between the lines within the paragraph)

This is a sentence. This is the second sentence (which has wrapped) if the line is long enough.
This is the second sentence.

n/a

(warning) As a result of this inconsistency, it is recommended that we never use a carriage return at the end of a line unless:

a) it is to mark the end of a paragraph, in which case it should be followed by a empty line (see the "Paragraphs" section) , or

b) We want a line break within in the paragraph, in which case we append 2 spaces to the end of the line (see the "Line breaks" section below).

ParagraphsTo force a line break, insert an empty line
This is the first paragraph, which has a single long sentence that will be wrapped.  It also has a second, shorted sentence.

This is the second paragraph.

n/a


Line breaksTo force a line break, finish the line with 2 spaces.  
Line 1, which has 2 spaces at the end of it.  
Line 2, forced by a line break.

Second paragraph.
Line 1, which has 2 spaces at the end of it.--
Line 2, forced by a line break.

Second paragraph.

Notice there is not as much space between the lines within a paragraph (as compared to the space between the paragraphs)
Multiple Blank lines

Add a backslash (\) on a line by itself in order to add an additional blank paragraph.


First paragraph.


Second paragraph.

\
Third paragraph.


n/a

NB: Markdown treats multiple blank lines as a single line.
HeadingsOne or more # symbols indicate a heading.  We user three (###) as that makes the headings a reasonable size (using a single # results in very large headings)
### 1. Heading
This is my content


n/a


Headings separated by carriage returnsIt makes no difference to the output if you place one or more blank lines after the heading.
### 1. Heading

This is my content


n/a

Adding the extra blank line is a matter of personal choice
Headings may require a blank line before themSome engines require a blank line before a heading, otherwise the heading is considered a continuation of the previous line.
### 1. Heading
This is my content
### 2. Another Heading
More content


n/a

Without a blank line before the second heading, the second heading may be interpreted as continuation of the previous line.

(warning) As a result of this inconsistency, it is recommended that a blank line is always inserted before a heading. 

Headings are manually numberedThe number in the heading is not considered special and you must manually make sure they are correct
### 1. Heading
This is my content

### 1. Another Heading
More content


n/a

In this case, the second heading needed to be "### 2. Another Heading"
Number lists

Use a number, followed by a period to indicate the item is part of a list - e.g. "1."


Here is a list  

1. Item 1
2. Item 2  
3. Item 3


n/a

Note that there is a space before the first item in the list
Numbered lists are automatically numberedThe list items are automatically number, so even if you create a list with all items identified as "1.", they get renumbered
Here is a list  

1. Item 1
1. Item 2  
1. Item 3


n/a


Numbered items with line breaksIf you add a line break to a numbered item (2 spaces after it), the next line will be indented correctly and follow on nicely
Here is a list

1. Item 1  
  Some info for item 2
2. Item 2
3. Item 3
  Some info for item 3  
  And even more.
Here is a list

1. Item 1--
--Some info for item 2
2. Item 2
3. Item 3  
--Some info for item 3--
--And even more.

Although the additional lines have been prefixed with 2 spaces, this is not mandatory.

However, as it makes the intent of the raw markdown more obvious, it is recommended,


Indenting numbered items

Markdown generally does not allow lines to be indented and you can not force a line to be indented by adding spaces to it.

That said, you can use 2 or more spaces to indent text if that line is considered part of a numbered item block.

Here is a list

1. Item 1

    Some info for item 2
2. Item 2
3. Item 3  
    Some info for item 3

    And even more.
Here is a list

1. Item 1

----Some info for item 2
2. Item 2
3. Item 3--
----Some info for item 3  

----And even more.

If you do prefix a line with one to 3 spaces (assuming it is not part of a numbered item block), the spaces are ignored. 

If you prefix it with 4 or more spaces, engines will recognise that as an indented code block and format the text in a fixed width font.

Nested Numbered Items (2 levels)We use alphabetic items to get a second level of nested numbered items - e.g. "a)"
1. Item 1  
  a) Item 1a.  This item has a long description that will wrap if I keep typing.  
  Another line for 1a.  
  b) Item 1b
2. Item 2  
  a) Item 2a  
  b) Item 2b  
  Some text for item 2b
1. Item 1--
--a) Item 1a.  This item has a long description that will wrap if I keep typing.--
--Another line for 1a.--
--b) Item 1b
2. Item 2--
--a) Item 2a--
--b) Item 2b--
--Some text for item 2b

(warning) This second level of numbering is not an inbuilt markdown formatting feature. 

We are just taking advantage of the line break feature (2 spaces at the end of a line) to get what looks to be a second level of numbering.

One of the implications of this is that if the text for the 2 level item is long and is wrapped, then second line doesn't indent properly. i.e. you see this:

rather than this:

(warning) Although the additional lines have been prefixed with 2 spaces, this is not mandatory.

However, as it makes the intent of the raw markdown more obvious, it is recommended,

Nested Numbered Items (3 levels)

We use numbered items to get a third level of nested numbered items - e.g. "1."

This is the second level of "real" nesting and to achieve that we prefix the second level of numbers with 4 spaces - e..g "    1."


Unnumbered text

1. Item 1  
  a) Item 1.a
    1. Item 1.a.1
    2. Item 1.a.2  
        Some text for item 1.a.2  
        Another line for item 1.a.2

2. Item 2  
  a) Item 2.a  
  b) Item 2.b
    1. Item 2.b.1
    2. Item 2.b.2  
        Some text text for item 2.b.2


Unnumbered text
 
1. Item 1--
--a) Item 1.a
----1. Item 1.a.1
----2. Item 1.a.2--
--------Some text for item 1.a.2--
--------Another line for item 1.a.2
 
2. Item 2--
--a) Item 2.a--
--b) Item 2.b
----1. Item 2.b.1
----2. Item 2.b.2--
--------Some text text for item 2.b.2