Style Guide¶

Documents are written in Markdown format, converted to HTML using the MyST parser. The following markdown extensions are enabled:

TODO

Headings¶

Headings are used to structure the document. Use # for top-level headings, ## for second-level headings, and so on. Each individual document (.md) should have only one top-level heading.

# Top-level heading
## Second-level heading
### Third-level heading
#### Fourth-level heading
##### Fifth-level heading
###### Sixth-level heading

Emphasis¶

Bold text is used to emphasize important information, where there is no specific semantic meaning or semantic modifier available.

Use **double asterisks** for bold text.

Italic¶

Italic text is used to introduce new terms or concepts.

Use _underscores_ to make text italic.

Literals¶

This text has a literal inline code span.

This text has a `literal` inline code span.

Literal Values¶

The literal value modifier should be used to convey discrete values or choices.

Example 1

Please select either Red or Blue.

Example 2

Value	Description
`Red`	The color red.
`Blue`	The color blue.

Semantic Literal Modifiers¶

Semantic Literal Modifiers are used to modify the appearance of inline code spans to convey different semantic meanings. They promote consistency and readability in the documentation and should be preferred over stylistic modifiers and generic markdown styles where possible.

Semantic Modifier	Example	Appearance	Use Case
No modifier	`foo`	`foo`	A literal value.
{.page-ref}	`Settings`{.page-ref}	The `Settings` page	A page reference.
{.link-ref}	Click `Settings`{.link-ref}	Click `Settings`	A link reference.
{.button}	`Default`{.button}	`Default`	Default button reference.
{.button .primary}	`Primary`{.button .primary}	`Primary`	Primary button reference.
{.button .dismiss}	`Dismiss`{.button .dismiss}	`Dismiss`	Dismiss button reference.
{.button .secondary}	`Secondary`{.button .secondary}	`Secondary`	Secondary button reference.
{.button .warning}	`Warning`{.button .warning}	`Warning`	Warning button reference.
{.button .danger}	`Danger`{.button .danger}	`Danger`	Danger button reference.
{.button .help}	`Help`{.button .help}	`Help`	Help button reference.
{.button .plain}	`I am White`{.button .plain}	`Plain`	Plain button reference.

Example

Use `Submit`{.button .primary} instead of `Submit`{.button .blue}.

Stylistic Literal Modifiers¶

Stylistic literal modifiers modify the appearance of inline code spans for stylistic purposes only. Stylistic modifiers should be used sparingly and only when a semantic modifier is not available.

Modifier	Example	Appearance	Use Case
{.button .blue}	`I am Blue`{.button .blue}	`I am Blue`	Blue button reference.
{.button .gray}	`I am Gray`{.button .gray}	`I am Gray`	A dismiss or gray button reference (.gray or .grey OK)
{.button .green}	`I am Green`{.button .green}	`I am Green`	A secondary or green button reference.
{.button .orange}	`I am Orange`{.button .orange}	`I am Orange`	A warning or orange button reference.
{.button .red}	`I am Red`{.button .red}	`I am Red`	A red button reference.
{.button .purple}	`I am Purple`{.button .purple}	`I am Purple`	A purple button reference.
{.button .white}	`I am White`{.button .white}	`I am White`	A white button reference.

Home Link¶

The home link is a special link reference. It is used to refer to the home page of the NETLAB+ system (i.e. the administrator home page or user’s MyNetlab page). The home link is rendered by using the {{ home }} variable.

Example

Navigate to {{ home }}

Result

Navigate to

Call to Action¶

The call to action is an icon ( ) that is used to indicate a step or to-do.

Example

{{ action }} Insert a banana into the flux capacitor.

{{ action }} Click the `Engage`{.button .secondary} button to jump to warp 3.

Result

Insert a banana into the flux capacitor.

Click the Engage button to jump to warp 3.

Links¶

Hyperlinks are automatically converted to HTML links and styled accordingly.

I am a link

Example

[I am a link](#foo-bar)

External Links¶

External links automatically open in a new tab and add an external icon to the link.

I am an external link

[I am an external link](https://www.example.com)

Admonitions¶

Note¶

Note

It provides additional information or context to the reader. This is an external link.

:::{note}
It provides `additional information` or context to the reader.
This is an [external link](https://en.wikipedia.org).
:::

Tip¶

Tip

It provides helpful information or advice to the reader. This is an external link.

:::{tip}
It provides `helpful information` or advice to the reader.
This is an [external link](https://en.wikipedia.org).
:::

Warning¶

Warning

It provides a warning or caution to the reader. This is an external link.

:::{warning}
It provides a `warning or caution` to the reader.
This is an [external link](https://en.wikipedia.org).
:::

Danger¶

Danger

It provides a super serious warning to the reader. This is an external link.

:::{danger}
It provides a `super serious warning` to the reader.
This is an [external link](https://en.wikipedia.org).
:::

Custom¶

Foobar !!!

This is a custom admonition using the admonition directive. This is an external link.

:::{admonition} Foobar !!!
:class: danger
This is a custom admonition using the `admonition` directive.
This is an [external link](https://en.wikipedia.org).
:::

You may change the title of an admonition by using the admonition directive. The :class: option allows you to specify the class of the admonition, which can be one of the following classes.

Class	Color
note	blue
tip	green
warning	orange
danger	red

Blockquote¶

> This is a block quote. It is used to display quoted text or other content.

Result

This is a block quote. It is used to display quoted text or other content.

Field Lists¶

Use field lists to document form values. The name of each field is displayed in bold and condensed font, similar to the labels used in NETLAB+ forms.

:Username: The name of the user account. This is the name that will be used to
log in to NETLAB+.

:Password: The password for the user account. This is the password that will be
used to log in to NETLAB+.

Result

Username:: The name of the user account. This is the name that will be used to log in to NETLAB+.
Password:: The password for the user account. This is the password that will be used to log in to NETLAB+.

Horizontal Rules¶

Use horizontal rules to separate sections of text. A horizontal rule is created by typing three hyphens on a line by itself. It is recommended to place a horizontal rule between major sections of a document.

---

Tight Lists¶

Tight lists are used to create a list of items without any blank lines between the items. Normally bulleted lists and numbered lists have a blank line between each item, which is appropriate for longer paragraphs. Tight lists do not have any blank lines between the items.

Regular List

Item 1
Item 2
Item 3

Tight List

Item 1
Item 2
Item 3

To create a tight list, place the {.tight-list} directive on the line immediately before the list.

{.tight-list}
* Item 1
* Item 2
* Item 3

Code Blocks¶

Use code blocks to display code or other text that should not be formatted. Code blocks are created by indenting the text with four spaces or one tab. Code blocks are typically used to display code snippets, configuration files, or other text that should not be formatted.

Both triple backticks (```) and MyST colon fences (:::) can be used to create code blocks.

```
/bin/bash
echo "Hello, World!"
```

Result

#!/bin/bash
echo "Hello, World!"

Images¶

There are two ways to include images in your documents.

The first is to use the standard Markdown syntax for images.

![Alt text](https://some-external-url)
![Alt text](media/image.png)

Result Cloud Security Automation

The second and recommended option is to use the MyST image directive. The image directive is more flexible and allows you to specify additional options such as the image scale, alt text, and caption.

Tip

The scale is a percentage of the original size. Choose a scale that causes the text in the image to appear at the same size as the text in the document.

:::{image} media/pan_card.png
:alt: Cloud Security Automation
:scale: 50%
:::

Result

Tables¶

MyST Table formats are supported:

Github Flavored Markdown
List Tables
CSV Tables
Caption Tables

Github Flavored Markdown¶

This is the most common table format. For large cells, consider using a list-table instead.

:::
| Header 1 | Header 2 | Header 3 |
| :------- | :------: | -------: |
| Left     |  Center  |    Right |
:::

Result

Header 1	Header 2	Header 3
Left	Center	Right

List Tables¶

List tables provide a list-oriented format for tables.

:::{list-table} Frozen Delights!
:widths: 15 10 30
:header-rows: 1

*   - Treat
    - Quantity
    - Description
*   - Albatross
    - 2.99
    - On a stick!
*   - Crunchy Frog
    - 1.49
    - If we took the bones out, it wouldn't be crunchy, now would it?
*   - Gannet Ripple
    - 1.99
    - On a stick!
:::

Result

Frozen Delights!¶
Treat	Quantity	Description
Albatross	2.99	On a stick!
Crunchy Frog	1.49	If we took the bones out, it wouldn’t be crunchy, now would it?
Gannet Ripple	1.99	On a stick!

Caption Tables¶

These are similar to Github flavored markdown tables, but with a caption.

:::{table} Broken Code Example
:width: 50%
:align: center

| foo | bar | hooka |
| --- | --- | ----- |
| baz | bim | pipe  |
:::

Result

Broken Code Example¶
foo	bar	hooka
baz	bim	pipe

CSV Tables¶

:::{csv-table} Frozen Delights!
:header-rows: 1
:widths: 15, 10, 30

"Treat", "Quantity", "Description"
"Albatross", 2.99, "On a stick!"
"Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be crunchy, now would it?"
"Gannet Ripple", 1.99, "On a stick!"
:::

Result

Frozen Delights!¶
Treat	Quantity	Description
Albatross	2.99	On a stick!
Crunchy Frog	1.49	If we took the bones out, it wouldn’t be crunchy, now would it?
Gannet Ripple	1.99	On a stick!

Text Substitutions¶

Text substitutions are used to replace text in the document with a variable or other value. This is useful for replacing text that may change frequently or for replacing text that is used in multiple places in the document.

{{ variable_name }}

The following variables are available:

Variable Name	Description
`{{netlab_major_version}}`	The current major version of NETLAB+ (e.g. 25).
`{{netlab_stable_version}}`	The current stable version of NETLAB+ (e.g. 25.1.1).
`{{netlab_beta_version}}`	The current beta version of NETLAB+ (e.g. 25.1.1)