Basic Markdown Features
Read time: 1 minute
Revision History
| Version | Date | Revision Author | Summary of changes |
|---|---|---|---|
| 1.0 | 2024-01-14 | Chris Collins | Initial version |
| --- | --- | --- | --- |
Welcome to the TLC Technology Wiki - below are some basic instructions that should help when it comes to compiling your first markdown document.
Documents can be written in the MD or MDX format and can be edited using the Azure DevOps wiki, Visual Studio Code or any other markdown editor.
For compatibility it is best to ensure file names do not contain spaces, you can use dashes for example - these can be amended using the Document IDs if required.
Markdown
Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).
The Docusaurus documentation covers a lot of markdown features and details can be found here:
We will cover a few of the main features below:
Headings
To create headings / subheadings you can use the following syntax - notice how levels 2-5 are displayed on the right and make up the table of contents, they are also clickable.
These relate to the H1 to H5 header settings in Azure Devops and other markdown editors.
# This is level 1 (document title)
## This is level 2
### This is level 3
#### This is level 4
##### This is level 5
This is level 1 (document title)
This is level 2
This is level 3
This is level 4
This is level 5
Basic text
The following characters are not allowed and will cause build errors unless entered inline or using the \
Forward slash - /
Curly Brackets - { }
A paragraph requires no special syntax in Markdown.
To format text as bold, you enclose it in two asterisks. To format text as italic, you enclose it in a single asterisk:
This text is **bold**.
This text is *italic*.
This text is both ***bold and italic***.
This text is bold.
This text is italic.
This text is both bold and italic.
Using a double space at the end of a line forces a newline
Numbered lists and bullet lists
To create numbered lists, begin a line with 1. or 1), but don’t use both formats within the same list. You don’t need to specify the numbers.
1. This is step 1.
1. This is the next step.
1. This is yet another step, the third.
- This is step 1.
- This is the next step.
- This is yet another step, the third.
To create bullet lists, begin a line with * or - or +, but don’t mix the formats within the same list. (Do not mix bullet formats, such as * and +, within the same document.)
* First item in an unordered list.
* Another item.
* Here we go again.
- First item in an unordered list. \
- Another item. \
- Here we go again.
Tables
Tables are not part of the core Markdown specification. Best practice is to avoid using multiple lines in tables. You can create tables by using the pipe (|) character to delineate columns and rows. Hyphens create each column’s header, while pipes separate each column. Include a blank line before your table so it’s rendered correctly.
| Header | Another header | Yet another header |
|--- |--- |--- |
| row 1 | column 2 | column 3 |
| row 2 | row 2 column 2 | row 2 column 3 |
| Header | Another header | Yet another header |
|---|---|---|
| row 1 | column 2 | column 3 |
| row 2 | row 2 column 2 | row 2 column 3 |
Links
The Markdown syntax for an inline link consists of the [link text] portion, which is the text that will be hyperlinked, followed by the (file-name / URL) portion, which is the URL or file name that’s being linked to:
Document Link
[Document IDs](#document-ids)
Image Link
[Link Text](.attachments/docusaurus-4f7a336c-f668-468d-a29a-a0b85623c8c0.png)
URL Link
[TLC Worldwide](https://www.tlcworldwide.com)
When linking to an internal section of a document remember to substitute any spaces with a - amd use lower characters
For example Document IDs becomes document-ids
Images
Images need to be added to the root .attachments folder and cannot contain any spaces.
 |
|---|
Code blocks
Markdown supports the placement of code blocks both inline in a sentence and as a separate “fenced” block between sentences.
Use back ticks (`) to create inline code styles within a paragraph. To create a specific multi-line code block, add three back ticks (```) before and after the code block (called a “fenced code block” in Markdown and just a “code block” component in AEM). For fenced code blocks, add the code language after the first set of back ticks so that Markdown correctly highlights code syntax. Example: ```\javascript
This is `inline code` within a paragraph of text.
This is inline code within a paragraph of text.
This is inline code within a paragraph of text.
This is a fenced code block:
function test() {
console.log("notice the blank line before this function?");
Tags
You can add tags to your documents, which introduces another dimension of categorization in addition to the sidebar. Tags are passed in the front matter as a list of labels:
---
id: doc-with-tags
title: A doc with tags
tags:
- Demo
- Getting started
---
Tags can also be declared with tags: [Demo, Getting started].
Document IDs
Every document has a unique id. By default, a document id is the name of the document (without the extension) relative to the root docs directory.
For example, the ID of greeting.md is greeting, and the ID of guide/hello.md is guide/hello.
website # Root directory of your site
└── docs
├── greeting.md
└── guide
└── hello.md
However, the last part of the id can be defined by the user in the front matter. For example, if guide/hello.md's content is defined as below, its final id is guide/part1.
---
id: part1
---
Lorem ipsum
The ID is used to refer to a document when hand-writing sidebars, or when using docs-related layout components or hooks.
Notification Boxes
These can be useful when highlighting certain points and can be created using the following syntax - simply add the info / note / warning / danger or tip after the triple colons
:::info
Example of an info box
:::
You can then add any text after the label to customise it
:::info[My Information]
Example of an info box
:::
Example of an info box
Examples of all the notification boxes you can create
Example of an info box
Example of a note box
Example of a tip box
Example of a warning box
Example of a danger box
Toggles
Toggles are a good way to consolidate tables on pages. An example of a toggle to show a table
<details>
<summary>Toggle me!</summary>
| Rank | Platform |
|------|-----------|
| 1| Cosmos |
| 2| MRP |
| 3| RFA |
</details>
Toggle me!
| Rank | Platform |
|---|---|
| 1 | Cosmos |
| 2 | MRP |
| 3 | RFA |
Nested Toggles
<details>
<summary>Toggle me!</summary>
<div>
<div>This is the detailed content</div>
<br/>
<details>
<summary>
Nested toggle! Some surprise inside...
</summary>
<div>😲😲😲😲😲</div>
</details>
</div>
</details>
An example of a nested toggle to show a table
Toggle me!
Nested toggle! Some surprise inside...
Quotes
Quotes can also be easily added
> Easy to maintain open source documentation websites.
>
> — Docusaurus
Easy to maintain open source documentation websites.
— Docusaurus
Videos
Videos can be embedded using the following syntax - these links can be obtained from the share settings and embed options
<iframe width="853" height="480" src="VIDEO URL" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
YouTube:
Microsoft Stream:
Azure Blob:
VSCode
As stated you can use the Azure DevOps wiki to create documents and it does provide a simple GUI based interface to create and edit them, however it you do want to use any of the feature outlined above you will need to use vscode and edit the files directly.
VS Code has two extensions that I highly recommend
Markdown Editor - provides a Word like editor for Markdown
Code spell checker - helps sense check your spelling
Just remember if using the Markdown editor plugin to change your default image directory to ${projectRoot}/www/docs/.attachments