Markdown Syntax

The vCZYZ KB supports an enhanced and slightly modified version of the Markdown specification. This document showcases a summary of common syntax.

If you’re already familiar with Markdown, first review the following sections as they differ from the ‘normal’ Markdown standard:

• the Heading Rules section.
• the instructions for writing Links to other pages in the Other Common Elements section.

Then, you may skip to the next document.

Paragraphs

Write paragraphs normally. Prettier will auto-wrap your text as you write, but as Markdown ignores single line breaks, those added by Prettier will have no effect on the rendered document.

In order to start a new paragraph like this, separate them with a single blank line.

Headings

## Heading 2

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6

Heading Rules

• Heading 1 (#) is not used, as the document title is rendered as a Heading 1. Always start with Heading 2.
• This also means you effectively have 5 levels to organize your docs (2-6).
• Skipping down heading levels is not allowed. For instance, a Heading 4 cannot be directly inside a Heading 2, there must also be a Heading 3 before it.
• Heading names cannot be duplicated within a document, as this would break links.

Note

Only Headings 2 & 3 show up in the “On this page” navigation bar along the right side of the screen.

Lists

Unordered lists:

• Item 1
  1. Ordered lists can be nested inside unordered lists
• Item 2
  • Nested Item
    • Doubly nested item
• Item 3

- Item 1
  1. Ordered lists can be nested inside unordered lists
- Item 2
  - Nested Item
    - Doubly nested item
- Item 3

Ordered lists:

1. Item 1

   Tip

   Callouts and other block-level elements can be added in lists if they’re indented properly.

2. Item 2

   1. Nested Item 1
      1. Doubly nested item 1
      2. Doubly nested item 2
   2. Nested Item 2
      • Unordered items can exist in ordered lists

3. Item 3

1. Item 1

   > [!tip]  
   > Callouts and other block-level elements can be added in lists if they're
   > indented properly.

2. Item 2
   1. Nested Item 1
      1. Doubly nested item 1
      2. Doubly nested item 2
   2. Nested Item 2
      - Unordered items can exist in ordered lists
3. Item 3

Code Blocks

Type three backticks in a row (`). VS Code should autofill the closing triple backticks for you. Add a new line and insert your code in between. You also need to specify what language your code is written in on the first line.

```python
print(“Hello world!”)
```

print("Hello world!")

Checkboxes

- [ ] Item 1
- [x] Item 2
- [ ] Item 3

• Item 1
• Item 2
• Item 3

Other Common Elements

• Italics *Italics*
• Bold **Bold**
• Bold italics ***Bold italics***
• Links [Links](https://google.com)
  • If you’re like me and can’t remember whether the bracket or parenthesis comes first, copy the URL to your clipboard, highlight the text you want to apply the link to and paste. VS Code should handle the formatting for you.
  • To link to a heading, begin the link section with a ’#’ and write the heading title in all lowercase, replacing any spaces with hyphens. [link text](#other-common-elements)
  • To link to another page, write the URL beginning from the first slash. Do NOT use the filename or relative paths. [link text](/contributors/markdown)
  • These methods can be combined. [link text](/contributors/markdown#other-common-elements)
  • The Starlight Links plugin can help autocomplete links in this format.
• Images: Same as a link, but insert an exclamation mark (!) in front.
• inline code: Surround the text with single backticks (`).
• Tables: See this guide.
• If you need to use a formatting character like * or [] in plaintext, prepend each with a backslash (\).
• Horizontal Rules: --- on a separate line.

---

Full List of Syntax

A comprehensive list and usage guide of basic Markdown syntax is available here.

The KB also supports additional syntax available through the underlying platform, Astro Starlight. You can find more information here. However, do NOT use Asides as we have added a custom plugin for Callouts. More information is available in the next document.

Blockquotes

Normal blockquotes look like this.

> Normal blockquotes look like this.

Normal blockquotes look like this.

You can also nest blockquotes.

> Normal blockquotes look like this.
>
> > You can also nest blockquotes.