Basic Formatting Documentation

Introduction

Documentation in the COBD Docs system is written using a variation on the syntax from the Markdown specification by John Gruber.

The Markdown variant used in the COBD Docs system allows for writing documentation that can be reused across organizational units using an easy-to-read, easy-to-write plain text format. This plain text representation can then be converted to structurally valid HTML by the COBD Docs system for display on the web. Markdown was selected for use in the COBD Docs system for its ease of editing and relatively easy learning curve. According to John Gruber, “the overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. …the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.” While the Markdown variant used in the COBD Docs system does introduce a few system-generated html tags and a number of custom placeholder shortcodes, into the mix, it is still generally very easy to read.

Basic Markdown Syntax

Paragraphs

A paragraph is defined as one or more lines of text, separated by at least one empty line:

This is a small paragraph illustrating how 
Markdown works. This paragraph span on many 
lines.

This is a second paragraph.

Here is the result:

This is a small paragraph illustrating how Markdown works. This paragraph span on many lines.

This is a second paragraph.

Line breaks inserted in the text are removed from the final result: the web browser is in charge of breaking upthe lines depending on the available space. If you really want to force a line break somewhere, insert two spaces at the end of the line.

Basic Lists

Markdown can create two types of basic lists: numbered lists (ordered) and bullet lists (unordored).

Ordered Lists

To create and ordered list, use a number followed by a dot as the item marker:

1. Cane Travel
2. Assistive Technology
3. Home Management
4. Braille and Tactile Skills

This gives the result:

  1. Cane Travel
  2. Assistive Technology
  3. Home Management
  4. Braille and Tactile Skills

If an ordered list starts with a number different than 1, the Markdown Extra variant used by COBD Docs will honour that in the output.

Unordered Lists

To create an unordered list, use *, +, or – as item markers:

* Braille Literacy Camp
* Teen TECH Camp
* Linda Evans Memorial Music Camp
* Adult Retreat

This gives the result:

  • Braille Literacy Camp
  • Teen TECH Camp
  • Linda Evans Memorial Music Camp
  • Adult Retreat

Other Notes About Lists

Lists can be nested by indenting by four spaces the lists on the second level:

+ Training Subjects
    1. Cane Travel
    2. Assistive Technology
    3. Home Management
    4. Braille and Tactile Skills
+ Summer Independence Camps
    * Braille Literacy Camp
    * Teen TECH Camp
    * Linda Evans Memorial Music Camp
    * Adult Retreat

This gives the result:

  • Training Subjects
    1. Cane Travel
    2. Assistive Technology
    3. Home Management
    4. Braille and Tactile Skills
  • Summer Independence Camps
    • Braille Literacy Camp
    • Teen TECH Camp
    • Linda Evans Memorial Music Camp
    • Adult Retreat

If your list contains entire paragraphs, leave an empty line between list items. To write more than one paragraph under the same item, make sure that they are indented by 4 spaces:

1. First paragraph.

    Second paragraph.

2. Another list item.

3. Yet another.

  1. First paragraph.

    Second paragraph.

  2. Another list item.

  3. Yet another.

Definition Lists

The Markdown Extra variant supported by the COBD Docs system implements definition lists. Definition lists are made of terms and definitions of these terms, much like in a dictionary.

A simple definition list in Markdown Extra is made of a single-line term followed by a colon and the definition for that term.

Apple
:   Pomaceous fruit of plants of the genus Malus in 
    the family Rosaceae.

Orange
:   The fruit of an evergreen tree of the genus Citrus.

Which gives the result:

Apple
Pomaceous fruit of plants of the genus Malus in
the family Rosaceae.
Orange
The fruit of an evergreen tree of the genus Citrus.

Terms must be separated from the previous definition by a blank line. Definitions can span on multiple lines, in which case they should be indented, though this is not strictly necessary.

Apple
:   Pomaceous fruit of plants of the genus Malus in 
the family Rosaceae.

Orange
:   The fruit of an evergreen tree of the genus Citrus.

Which gives the result:

Apple
Pomaceous fruit of plants of the genus Malus in
the family Rosaceae.
Orange
The fruit of an evergreen tree of the genus Citrus.

Each of the preceding definition lists will give the same HTML result:

Colons as definition markers typically start at the left margin, but may be indented by up to three spaces. Definition markers must be followed by one or more spaces.

Definition lists can have more than one definition associated with one term:

Apple
:   Pomaceous fruit of plants of the genus Malus in 
    the family Rosaceae.
:   An American computer company.

Orange
:   The fruit of an evergreen tree of the genus Citrus.
:   A colour.

Which gives the result:

Apple
Pomaceous fruit of plants of the genus Malus in
the family Rosaceae.
An American computer company.
Orange
The fruit of an evergreen tree of the genus Citrus.
A colour.

More than one term can also be associated to a definition:

Term 1
Term 2
:   Definition a

Term 3
:   Definition b

Which gives the result:

Term 1
Term 2
Definition a
Term 3
Definition b

If a definition is preceded by a blank line, Markdown Extra will wrap the definition in paragraph (<p>) tags in the HTML output. For example, this:

Apple

:   Pomaceous fruit of plants of the genus Malus in 
    the family Rosaceae.

Orange

:    The fruit of an evergreen tree of the genus Citrus.

Will give the result:

Apple

Pomaceous fruit of plants of the genus Malus in
the family Rosaceae.

Orange

The fruit of an evergreen tree of the genus Citrus.

And just like basic list items, definitions can contain multiple paragraphs, and include other block-level elements such as blockquotes, code blocks, lists, and even other definition lists.

Term 1

:   This is a definition with two paragraphs. Lorem ipsum 
    dolor sit amet, consectetuer adipiscing elit. Aliquam 
    hendrerit mi posuere lectus.

    Vestibulum enim wisi, viverra nec, fringilla in, laoreet
    vitae, risus.

:   Second definition for term 1, also wrapped in a paragraph
    because of the blank line preceding it.

Term 2

:   This definition has a code block, a blockquote and a list.

        code block.

    > block quote
    > on two lines.

    1.  first list item
    2.  second list item

Which gives the result:

Term 1

This is a definition with two paragraphs. Lorem ipsum
dolor sit amet, consectetuer adipiscing elit. Aliquam
hendrerit mi posuere lectus.

Vestibulum enim wisi, viverra nec, fringilla in, laoreet
vitae, risus.

Second definition for term 1, also wrapped in a paragraph
because of the blank line preceding it.

Term 2

This definition has a code block, a blockquote and a list.

code block.

block quote
on two lines.

  1. first list item
  2. second list item

Emphasis

Emphasis can be added to parts of text inside a paragraph. There is two types of emphasis: normal emphasis and strong emphasis. On most websites, emphasis is shown as italic while strong emphasis is bold.

To give emphasis to some text with Markdown, asterisks (\*) are used. Surrounding some text with one asterisk bar gives normal emphasis, while surrounding some text with two asterisks results in strong emphasis:

*normal emphasis with asterisks*

**strong emphasis with asterisks**

And it gives this result:

normal emphasis with asterisks

strong emphasis with asterisks

Please note: The rules for the original Markdown syntax allow underscores (_) to be used instead of asterisks for declaring emphasis. However, with the Markdown Extra variant supported by the COBD Docs system, underscores in the middle of a word are treated as literal characters. Underscore emphasis only works for whole words. For this reason, it is requested that only asterisks be used to denote emphasis in COBD Docs.

Links

Links to another document within the same handbook or links to an external website can be created in three ways, inline links, reference links, or automatic links.

Inline Links

Inline links allow linking some text to another web page. Surround the link with [brackets], followed by the URL inside parenthesis. Like this

[COBD Home](https://cobd.ca/)

[Advanced Formatting Documentation](20)

This gives the result:

COBD Home

Advanced Formatting Documentation

The second link illustrates the bests use case for inline links. It links to another page in this handbook by using the id of the page to be linked. Use inline links for this purpose whenever possible.

ReferenceLinks

While inline links can be used to express links to other websites, reference links are ideal for this purpose. They work the same as inline links, except that the URL does not need to be written in the middle of the paragraph, making text easier to read. Instead a name is given to the link and the URL is written on a separate line at the bottom of the document. It looks like:

You can find more information in the [COBD Bylaws](link1) or by [contacting us](link2).

Then, at the bottom of the document:

[link1]: https://docs.cobd.ca/cobd/bylaws/
[link2]: https://cobd.ca/contact/

The line that defined the URL is stripped from the final result and the bracketed text becomes a link:

You can find more information in the COBD Bylaws or by contacting us.

AUTOMATIC LINKS

If only a URL inserted into a document needs to be converted into a link, simply put the URL between angle brackets and Markdown will make a link out of it:

<https://cobd.ca/>

This gives the result:

https://cobd.ca/

Other Notes About Links

The Markdown specification allows links to include titles, which web browsers typically display as tooltips when a mouse hovers over the link. This functionality is not currently supported by the COBD Docs system.

Headings

Headings and sub-headings can be added to documents with Markdown. Headings can be inserted with up to six different levels of headings supported. To create a heading, simply insert the number of hash (#) characters that correspond to the desired heading level, followed by a space ( ), followed by the text of the heading:

# Heading 1

## Heading 2

###### Heading at level 6

Heading 1

Heading 2

Heading at level 6

When writing documentation it is important to keep headings at subsequent levels. The title of the documentation is automatically converted into a heading at level 1 and subsequent headings should therefore never start above level 2. Also, headings should only be used at sequential levels, meaning headings at level 3 should only be nested as sub-headings at level 2, headings at level 4 should only be nested as sub-headings at level 3, and so on. No levels should be skipped (e.g. headings at level 5 should never be directly nested within sections headed by headings at level 3).

Tables

The Markdown Extra variant used by COBD Docs add syntax for simple tables to the Markdown syntax. A “simple” table looks like this:

| First Header | Second Header |
| ------------- | ------------- |
| Content Cell | Content Cell |
| Content Cell | Content Cell |

This produces the result:

First Header Second Header
Content Cell Content Cell
Content Cell Content Cell

The first line contains column headers; the second line contains a mandatory separator line between the headers and the content; and each following line is a row in the table. Columns are always separated by the pipe (\|) character.

Alignment for each column can be specified by adding colons to separator lines. A colon at the left of the separator line will make the column left-aligned; a colon on the right of the line will make the column right-aligned; colons at both side means the column is center-aligned.

| Item      | Value |
| --------- | -----:|
| Computer  | $1600 |
| Phone     |   $12 |
| Pipe      |    $1 |

This gives the result:

Item Value
Computer $1600
Phone $12
Pipe $1

Span-level formatting can be applied to the content of each cell using regular Markdown syntax:

| Function name | Description                    |
| ------------- | ------------------------------ |
| `help()`      | Display the help window.       |
| `destroy()`   | **Destroy your computer!**     |
Function name Description
help() Display the help window.
destroy() Destroy your computer!

Blockquote

Blockquotes are inspired by the method used for quoting someone in an email discussion:

A quote about linear algebra:

> Consistent linear systems in real life are solved in 
> one of two ways: by direct calculation (using a matrix 
> factorization, for example) or by an iterative procedure 
> that generates a sequence of vectors that approach the 
> exact solution.

Thisgives the result:

A quote about linear algebra:

Consistent linear systems in real life are solved in
one of two ways: by direct calculation (using a matrix
factorization, for example) or by an iterative procedure
that generates a sequence of vectors that approach the
exact solution.

You can put more than one paragraph inside a blockquote. You can also put a second blockquote level, lists, etc.

Shortcodes

The COBD Docs system supports a variety of shortcodes, documented below. Shortcodes are placeholders wrapped in square brackets ([]). When a page is loaded, the shortcodes are replaced with their corresponding values as defined in the dictionary for the organization to which the handbook applies.

The examples written below must be surrounded by square brackets to be valid shortcodes. The brackets have been omitted to prevent the system from generating replacements.

HB

To aid in writing documentation that can be easily reused across organizational units, the “HB” shortcode allows for terms to be replaced from the organizational unit’s dictionary. This can be used to replace positions as they can vary across handbooks. For example, the term “evacuation-supervisor” may apply to the Executive Director in one organizational unit but that same role may be filled by the Camp Coordinator in another. The “HB” shortcode for this example would look like:

hb term=”evacuation-supervisor”

If a term has not yet been defined or that definition is missing from an organizational unit’s dictionary, the output will simply consist of the name of the term in a bold and underlined font.

There is no limit to the types of terms that can be expressed. Some additional examples are:

unit-name
The name of an affiliate, division, chapter or the COBD itself, such as “PTCB Division” or “Camp Bowen Division”.
Unit-type
one of “affiliate”, “division”, “chapter” or “organization”.

A full list of terms defined so far can be found in Appendix A.

If a new term is needed, simply contact IT Services and make a request for it to be added, giving a link to the documentation being worked on for context.