Markdown Basics

This topic covers the most important Markdown syntax.

Headings

Headings in Markdown are any line which is prefixed with a # (hash) symbol. The number of hashes indicates the level of the heading. The first content in the file after the metadata block must be the title as H1 heading (# Header). All major topics should be tagged further as header level 2 (## Header).

There are a total of 6 levels which you can make use of - but for most writing, you’ll rarely ever need more than 3.

Nota

Each Markdown file must have one and only one H1 heading.
There must be a space between the last # and heading text.
Header levels 4, 5 and 6 are not visible in affixes (right side of the page) and do not have anchor points.

In-Text Highlights

Astersisks and underscores are used to format text as bold or as italic. They are completely interchangeable.
Lorem markdownum propiusque rubet ergo quaerere Thebas iuvenes viscera * et _ et ` nec atque vetaris.

Lists

Bulleted List:

  • List item 1
  • List item 2
    • List item 2.1
    • List item 2.2
  • List item 3

Numbered List:

  1. List item 1
  2. List item 2
    1. List item 2.1
    2. List item 2.2
  3. List item 3

Tables

The simplest way to create a table in Markdown is to use pipes and lines. For a header, enter a dashed line after the first line. You can align the columns by using colons.

Header 1 Header 2 Header 3
Left Aligned Center Aligned Right Aligned
... ... ...

You can also use Tables Generator.

Source Code

Auto detection:

<AppPermissionRequests AllowAppOnlyPolicy="true">
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection" Right="Write"/>
</AppPermissionRequests>

Define language:

private void index(){
  MessageBox.Show("hello world");
}

Without color:

private void index(){
  MessageBox.Show("hello world");
}

Blockquotes

Blockquotes are created using the > character:

Caespite suo caesa colorem collo. Tamen thalamumque remisit turba. Has dominis fecundo ille, antraque, nec atque vetaris utque, Munychiosque. Neve saltumque mentae, iam umbram latratu. Securus nati Hecabe falsum sola non voluit terris ablata vinclisque pavor Fluctibus.

Alerts

The following alert types are available:

Nota

Caespite suo caesa, antraque, nec atque vetaris utque, Munychiosque. Neve saltumque mentae, iam umbram latratu. Securus nati Hecabe falsum sola non voluit terris ablata vinclisque pavor Fluctibus.

Propina

Caespite suo caesa, antraque, nec atque vetaris utque, Munychiosque. Neve saltumque mentae, iam umbram latratu. Securus nati Hecabe falsum sola non voluit terris ablata vinclisque pavor Fluctibus.

Importante

Caespite suo caesa, antraque, nec atque vetaris utque, Munychiosque. Neve saltumque mentae, iam umbram latratu. Securus nati Hecabe falsum sola non voluit terris ablata vinclisque pavor Fluctibus.

Precaución

Caespite suo caesa, antraque, nec atque vetaris utque, Munychiosque. Neve saltumque mentae, iam umbram latratu. Securus nati Hecabe falsum sola non voluit terris ablata vinclisque pavor Fluctibus.

Advertencia

Caespite suo caesa, antraque, nec atque vetaris utque, Munychiosque. Neve saltumque mentae, iam umbram latratu. Securus nati Hecabe falsum sola non voluit terris ablata vinclisque pavor Fluctibus.

Links point users to content in the same page, in other neighboring pages, or on external sites and URLs.

Use relative position of the target:

  • ./ = current directory
  • ../ = one directory above
  • ../media/file.demo = one directory above, in media folder, find file.demo
Propina

Best practice: All internal links should start with ./ or ../.

Precaución

Avoid using:

Media

If you want to use images, add them to the repository by using the path definition used for Links.

Propina

Best practice: Upload all images in the media folder. This folder is already part of the Demo project.

Images

The following file types are supported for images:

  • .jpg
  • .png
Nota

.bmp graphics don’t work in Markdown.

COSMO CONSULT

Videos

Avoid copying videos directly to the repository. Best practice here is to upload the video somewhere else and link to the video.

Useful Hints

HTML

Although Markdown supports inline HTML, HTML isn't recommended for publishing to Docs, and except for a limited list of values will cause build errors or warnings.

Comment syntax

Useful for sections that are not ready.

<!-- Comments -->

Line breaks (soft return)

In the editor, add two blank spaces at the end of the sentence and hit return.

Angle brackets

If you use angle brackets in text in your file - for example, to denote a placeholder - you need to manually encode the angle brackets. Otherwise, Markdown thinks that they're intended to be an HTML tag.

For example, encode <script name> as \<script name>.

Angle brackets don't have to be escaped in text formatted as inline code or in code blocks.

Nota

To display a literal character that would otherwise be used to format text in a Markdown document, add a backslash () in front of the character.

Apostrophes and quotation marks

If you copy from Word into a Markdown editor, the text might contain "smart" (curly) apostrophes or quotation marks. These need to be encoded or changed to basic apostrophes or quotation marks. Otherwise, you end up with things like this when the file is published: It’s.