Internal Syntax

Some extensions to the standard Markdown syntax have been added for the vCZYZ KB. They are described below.

It’s possible to add any Starlight, remark or rehype plugin to the KB to support further syntax extensions. If you find one that you think may be useful, let tech support know.

Important

The internal syntax will only be rendered properly on the website as it requires custom plugins. When editing locally in VS Code, you will only see the raw text in the Markdown Preview window. Therefore, be extra careful to follow the syntax rules.

Callouts

Callouts are a special type of blockquote that you can use when trying to highlight important information. The syntax is:

> [!type] Title text  
> Body text

Warning

Prettier will collapse your body text into the same line as the title text by default. To avoid this, add two spaces after the title text on the same line like so: Title text .

Callout Types

To use a specific callout, use the syntax above and type an all-lowercase version of the title or alias you would like as the callout type.

The title/alias determines the default title. If you want to keep the default title, add two spaces after the closing bracket of the type to prevent Prettier from collapsing it, then make a new line for your content. If you want to change the title, use the format shown above.

> [!note]  
> (the extra two spaces should be placed at the end of the line above)  
> This callout will have the default title of "Note".

Note

This callout will have the default title of “Note”.

Abstract

Alias: summary

Info

Todo

Tip

Aliases: hint, important

Success

Aliases: check, done

Question

Alias: help

Warning

Aliases: caution, attention

Fail

Aliases: failure, missing

Danger

Alias: error

Bug

Example

Quote

Alias: cite

You can make a callout collapsible by adding a hyphen after the closing bracket of the type.

> [!quote]- Some custom title  
> Some hidden content

Some custom title

Some hidden content

vCZYZ KB Callouts

There are several vCZYZ KB-specific callout types that you can use in addition to the callout types shown above. However, these differ in that they do not support having a title. The callout will show all text in one line (until it wraps), regardless of how many lines it has.

Aside from the zyzNote and zyzCaution types which can be used freely as subtler versions of the normal note and caution callouts, the rules on when to use these callout types can be found in Phraseology Formatting.

The callout types are abbreviated to avoid excessive line length. To help you remember:

• All start with zyz
• St = Syntax (which are also the ones with a blue background)
• Ex = Example
• Ph = Phraseology
• Con = Controller
• Plt = Pilot

> [!zyzNote] Supplementary information

> [!zyzCaution] This example shows how despite this callout spilling over
> multiple lines in the raw code, when rendered it is treated as if it was
> written on a single line. This differs from normal callouts where the first
> line is used as the title, with the content beginning on the second line.

> [!zyzStPh] Rules & syntax for phraseology

> [!zyzExCon] Examples of phraseology spoken by a controller

> [!zyzExPlt] Examples of phraseology spoken by a pilot

> [!zyzStData] Rules & syntax for information that is typed, not spoken

> [!zyzExData] Examples of information that is typed, not spoken

Renders as:

Supplementary information

This example shows how despite this callout spilling over multiple lines in the raw code, when rendered it is treated as if it was written on a single line. This differs from normal callouts where the first line is used as the title, with the content beginning on the second line.

Rules & syntax for phraseology

Examples of phraseology spoken by a controller

Examples of phraseology spoken by a pilot

Rules and syntax for information that is typed, not spoken

Examples of information that is typed, not spoken

Callout Icons

If you need just the icon from one of the ZYZ callouts (not the normal ones!) without the entire callout, use this directive and one of the ZYZ callout types:

:zyzIcon{icon=zyzNote} (...the example shows all icons)

Inline Callouts

Warning

Do not use this method of writing a callout unless you are in a table or other environment where the normal method does not work. If you use the inline format unnecessarily, your pull request will be rejected.

Markdown tables don’t support blockquotes, which means callouts also can’t be written in a table cell. The following directive permits adding a callout in a table cell:

# Normal callout, default title (or ZYZ titleless callout)

:co[hello I am **callout** content]{type=done}

:co[hello I am **callout** content]{type=zyzStPh}

# Callout with custom title

:co[If the title for an inline callout contains a space, encase the title in
quotes.]{type=missing title="You Failed!"}

Done

hello I am callout content

hello I am callout content

You Failed!

If the title for an inline callout contains a space, encase the title in quotes.

The ID (#id) and class (.class1 .class2) attributes can be added if necessary.

Inline List Directives

Warning

Do not use this method of writing a list unless you are in a table or other environment where the normal method does not work. If you use the inline format unnecessarily, your pull request will be rejected.

Lists are also block elements, and as such also don’t work inside table cells. The normal workaround is writing raw HTML like this:

<ul><li>Item 1</li><li>Item 2</li></ul>

…which isn’t ideal. The following directive allows creating lists (and nested lists) within a table:

| Col A                                            | Col B                           |
| ------------------------------------------------ | ------------------------------- |
| :list[**item1**;item2]                           | :list[item1;item2]{bullet=num}  |
| :list[item1:list[item2;item3]{bullet=num};item4] | :list[item1;item2]{bullet=none} |

Col A	Col B
item1 item2	item1 item2
item1 item2 item3 item4	item1 item2

Usage:

• Items must be separated by semicolons.
• Any normal inline Markdown syntax can be used (block-level elements like blockquotes don’t work).
• The attributes (curly braces) are optional. Options are:
  • bullet: Type of bullet to use. If the attribute is omitted, the list will be a bullet list (HTML <ul>). Options:
    • num: Numbered list (HTML <ol>).
    • none: No bullets. Use instead of writing a bunch of <br>s. Do not use this type in, or as a nested list.
  • #someId: Sets the HTML ID of the list.
  • .class1 .class2: Sets the HTML class(es) of the list.

Table Directives

The vCZYZ KB has certain styles that can be applied to Markdown tables. They are applied using directives, which is a line of text that starts with two colons (::) placed above the table that it is to be applied to and has special syntax.

Directives must be:

• Each on their own line
• Spaced by exactly one line:
  • Between the first directive and any content above it (unless it’s the first line in a doc),
  • Between each directive, and
  • Between the last directive and the table itself.

Other content...

::table{.class1}

::column{col=1 .class1}

::column{col=2 .class2}

| Header 1 | Header 2 |
| -------- | -------- |
| Cell 1   | Cell 2   |
| Cell 3   | Cell 4   |

Caution

As mentioned above, this syntax only works on the website. If you open the VS Code preview pane, you will see the directives displayed in plain text. The website will apply the styles and hide the directive. In other words, if you see the raw directive text visible on the website, you did not use it correctly.

For comparison’s sake, here’s a normal table:

Header 1	Header 2
Cell 1	Cell 2
Cell 3	Cell 4

Full Table Directives

The first type of directive is used to apply styles to the entire table. The keyword is table.

# To apply one style:

::table{.class1}

# To apply multiple styles:

::table{.class1 .class2 .class3} # ...and so on

The available styles (classes) to apply to the whole table are:

• .no-border:

  • Removes all outer and inner borders that are applied by default to Markdown tables.
  Hidden table class directive

  Header 1	Header 2
  Cell 1	Cell 2
  Cell 3	Cell 4

• .no-header:

  • Renders the first row as normal text instead of bolded, which it is by default.
  Note

  This removes the header ‘style’, but the header still ‘exists’ in terms of the specification. In other words, you treat the cell “Header 1” from the example as your first cell, and you must still include the table row containing the line of hyphens when you write the table.

  Hidden table class directive

  Header 1	Header 2
  Cell 1	Cell 2
  Cell 3	Cell 4

Table Column Directives

The second type of directive is used to apply styles to a single column of a table. The keyword is column.

The syntax is similar to the table style directive, but you must also specify which column the style is to be applied to. Columns are numbered from the left, beginning at 1.

# To apply one style:

::column{col=1 .class1}

# To apply multiple styles:

::column{col=1 .class1 .class2 .class3} # ...and so on

# To apply styles to multiple columns:

::column{col=1 .class1}

::column{col=2 .class1}

The available styles (classes) to apply to a column are:

• .syntax: Applies the ‘phraseology rules’ light blue shading colour to the entire column. Also offsets it to the right slightly to avoid the text touching the edge of the shading.

  Hidden table class directive

  Header 1	Header 2
  Cell 1	Cell 2
  Cell 3	Cell 4

• .no-wrap: Prevents the text in the column from wrapping onto a new line. This allows you to control the column width using the text within any cell.

  Warning

  The table may become wider than the page width if you aren’t careful. Use this style sparingly and keep in mind some people may be reading on mobile devices with slimmer screens. Below is an extremely exaggerated example of the potential consequences.

  Hidden table class directive

  Header 1	Header 2
  Cell 1 Extra text Extra text Extra text Extra text Extra text Extra text Extra text Extra text Extra text Extra text	Cell 2
  Cell 3	Cell 4

Table Cell Merging

Table Cells can be merged by filling a cell with one of the special characters below. If any other characters aside from the merging special character are present in a cell, it will not be merged.

• >: Merge cell to the right
• ^: Merge cell upwards

Only the content in the rightmost cell when merging horizontally or the topmost cell when merging vertically will be kept.

| Header 1 | Header 2                             |
| -------- | ------------------------------------ |
| Cell 1   | Cell 2                               |
| >        | Cell 3 text text text text text text |
| >        | Cell 4 text text text text text text |
| Cell 5   | Cell 6                               |
| ^        | Cell 7                               |
| ^        | Cell 8                               |

Header 1	Header 2
Cell 1	Cell 2
Cell 3 text text text text text text
Cell 4 text text text text text text
Cell 5	Cell 6
	Cell 7
	Cell 8