Markdown

Markdown is a lightweight markup language for creating formatted text.

It is used in ContactsLaw for notes (associated with contacts, matters, etc) as well as in document templates.

One of the principal reasons for using Markdown (as opposed to other representations, such as Rich Text Format or HTML) is that it separates markup (paragraphs, lists, headings, etc) from style (colours, fonts, etc). This means that the same content can be displayed in different ways without affecting its semantics. This is particularly useful in document production as the author of the template does not need to be aware of any business-specific branding or design and, indeed, these can be altered freely without affecting content specifications.

The Desktop App provides a WYSIWYG editor, such that users do not need to learn the Markdown syntax. The Web App, however, requires Markdown to be entered directly, displaying a separate preview of the formatting.

Standard Features

ContactsLaw supports the following standard Markdown features:

Markdown	Formatting	Remarks
**Bold**	Bold
*Italic* or _Italic_	Italic
***Bold and Italic***	Bold and Italic
# Heading 1	Heading 1
## Heading 2	Heading 2
### Heading 3	Heading 3
#### Heading 4	Heading 4	Depending on the destination, up to 6 heading styles may be available.
1. Ordered List	Ordered List	List items are automatically numbered, so you need only place a '1' beside each.
- Unordered List	Unordered List
[Hyperlink](https://google.com)	Hyperlink
<https://google.com>	https://google.com
<name@email.com>	name@email.com	Automatically creates a "mailto:" link.
`Code  Span`	Code Span	Insignificant whitespace is preserved (this is not usually the case).
---		Horizontal line/separator.

Extended Features

ContactsLaw adds the following extended features:

Markdown	Formatting	Remarks
__Underline__	Underline	Not normally used in Markdown because it is easily confused with a hyperlink.
~~Strikethrough~~	Strikethrough
==Highlight==	Highlight	Uses the default highlight colour.
:smile:	😄	A range of emoji are supported.
~[Red Text](red)	Red Text	Colours can be referenced by name (see X11 color names) or by their hexadecimal RGB representation, e.g. ~[Red](color:#ff0000). It is expected that explicit colours would be used sparingly in practice.
~[Red Text](c:red)	Red Text	The "c:" prefix denotes the text colour.
~[Green Highlight](h:lime)	Green Highlight	The "h:" prefix denotes the highlight colour.
~[Multi](c:red,h:lime)	Multi

Tables

ContactsLaw also leverages established conventions for defining tables:

Markdown	Formatting	Remarks
|---|---| |Column1|Column2|	Column1 Column2	Without header row.
|Heading1|Heading2| |---|---| |Column1|Column2|	Heading1 Heading2 Column1 Column2
|---|---| |Column1|**Column2**|	Column1 Column2	Text in cells can be combined with other formatting, e.g. bold.
|---|---| |Column1 \\ Line2|Column2|	Column1 Line2 Column2	Line breaks inside cells use this special syntax.

At minimum, a table must include its column definitions and at least one row. Unlike other flavours of Markdown, we permit tables without a heading row.

Within a table cell, all types of formatting except those which create block-level elements (lists, etc) can be used.

In some cases, it may not be clear whether a table should be shown with borders. Replacing hyphens (-) in the column definition with equals signs (=) indicates that borders are required.

Images

ContactsLaw extends the established conventions for embedding images by adding support for explicit sizing and data URIs:

Markdown	Formatting	Remarks
!(https://url/to/img)
	Image Title	Depending on the destination, the title may appear as a tooltip.
!(https://url/to/img 30x30mm)		Both width and height specified (note: this may stretch the image). Units can be mm, cm, pt or px.
!(https://url/to/img w30mm)		Use prefix "w" for width, or "h" for height.
!(data:image/png;base64,VGhl ... ZveA==)		Note: Data has been truncated for brevity.

Any combination of the above features is considered valid. At minimum, an image must have a source URL.

Depending on the destination format, images may either be directly embedded or linked to an external resource. If the latter does not have a public URL, the image’s origin should match the document's.

ContactsLaw will attempt to degrade gracefully if images cannot be displayed, e.g. by showing placeholders or alternative text. Images will be omitted entirely if unsupported by the destination format.

Native Features

Main page: Native Feature

Although Markdown is intended to be destination-agnostic, there are occasions where features native to a particular format need to be included in the document for quality reasons. For example, while it may be sufficient to use whitespace to denote an indent in some formats, it is more desirable to use a tab space in Microsoft Word.

Where present, these native features should always be accompanied by a fallback value.

Markdown	Formatting	Remarks
!		Tab space in Microsoft Word, otherwise 3 consecutive spaces.
Page !(.xlsx Formula ROW\(\))	Page 1	Page number in Microsoft Word, row number in Microsoft Excel, otherwise "1".

External Links

Markdown (Wikipedia)