Kitchen Sink

This page serves as a reference to the features supported by the MyST + Sphinx + Read The Docs stack that is used to create this wiki page. This page is probably best viewed in source which you can find with the “Edit on GitHub” link in the top right. If you are using Visual Studio Code, the MyST-Markdown plugin is recommended as it provides code snippets for the different directives that MyST adds to regular Markdown. In general, a block is surrounded by ::: followed by the name of the directive inside { }. Directives can have arguments, which are surrounded by : :.

For example of this:

:::{directive} Parameter
:argument:
:second-argument: Foobar
:::

Markup

Standard Github-flavored Markdown is available as a basis. You can find more information about it here. For completeness, here is a quick reference list:

Element	Markdown Syntax	Description
Header 1	`# Header 1`	Largest header, equivalent to `<h1>` in HTML.
Header 2	`## Header 2`	Second largest header
Header 3	`### Header 3`	Third largest header
Header 4	`#### Header 4`	Fourth largest header
Header 5	`##### Header 5`	Fifth largest header
Bold Text	`Bold`	Makes text bold
Italic Text	`_Italic_` or `Italic`	Makes text italic
Link	`[Text](URL)`	Creates a hyperlink with the provided text
Image	`![Alt text](URL)`	Embeds an image
Unordered List	`- Item`	Creates a bulleted list
Ordered List	`1. Item`	Creates a numbered list
Blockquote	`> Quote`	Creates a blockquote
Code (Inline)	`Code`	Displays inline code
Code (Block)	`<br>Code<br>`	Displays a block of code
Table	See source	Creates a table

Heading without TOC entry

A heading that will not show up in the table of contents

Subscript/Superscript

We can also write text in _subscript, or ^superscript or other hings

Abbreviations

Defining abbreviations, which have an explanation that is visible via hovering over the text: LIFO

Commands

Displaying a program that is available on the computer: rm

Keystrokes

Showing a combination of keystrokes that should be pressed by a person to achieve something: C-x C-f

Inline comments

Icons embedding

We can also provide images directly into the text: . The list of all icons can be found here.

Tables

Markdown-style

foo	bar
baz	bim

MyST style

Table with caption
foo	bar
baz	bim

Multi-column table

A list of
short items
that should be

displayed
horizontally

Links

A link that doesn’t have the URL locally, but hidden away in the bottom of the file. The link here would be the same as this link. We can also add footnotes, either as a manually-numbered reference[3], or an automatically-numbered reference[1]. Footnotes can also be a lot longer, too[2]. The actual content behind the footnote can be placed anywhere in the source file, but will always be rendered at the bottom of the page.

Footnotes

This is not part of the footnote.

Images

Markdown

The normal Markdown way: OpenSpace Logo

Centering images

But MyST also added a second method that has way more options. See their documentation for more information.

Captions

Or with captions underneath

https://source.unsplash.com/200x200/daily?cute+animals — We can also add captions to the images by using the `figure` environment

Dark and Light theme

We can use different images for light and dark themes

https://source.unsplash.com/200x200/daily?cute+dogs

https://source.unsplash.com/200x200/daily?cute+cats

Videos

Embedding videos does not work natively in Markdown and we need to fall back to raw HTML instead:

Callouts

MyST adds a bunch of different admonition styles, which are demonstrated here.

Attention

Caution

Danger

Error

Hint

Important

Note

Sidebar

There is the option to provide information in a sidebar as well. We’ll just add some more text here that makes it more obvious. Lorem ipsum dolor sit amet consectetur adipisicing elit. Accusamus, sunt voluptatum tenetur libero nulla esse veritatis accusantium earum commodi hic voluptatem officia culpa optio atque. Quaerat sed quibusdam ratione nam.

Markups

New in version 2.5: If something is only available in a specific version

Changed in version 3.1: Something has changed in this version

Deprecated since version 4.5: Something has been deprecated but not removed

Code Highlighting

Default language

-- There is no default language for code blocks
local abc = function()
  return [[
    a
  ]]
end

-- This is also true for standard Markdown code highlighting
function(abc)
  return abc + abc
end

Different language

-- But we can manually specify which language it is
local abc = function()
  return [[
    a
  ]]
end

-- Also for blocks
function(abc)
  return abc + abc
end

// It's possible to change the language for the syntax highlighting as well
std::vector<std::optional> foo() {
  return std::nullopt;
}

// Same for the standard Markdown, which is nicer for Visual Studio Code syntax highlighting
std::string_view bar() { return "abc"; }

Line number and captions

Line numbers and captions

// The directive-based way can have different options, for example to
// show line numbers and a caption
int foo() {
  // But it can be changed to C++ as well
  return 1 * 2 * 3 * 4;
}

Highlight lines// Highlighting some lines
int bar() {
  constexpr int One = 1;
  constexpr int Two = 2;
  constexpr int Three = 3;

  return One + Two + Three;
}

Function defintions

It is also possible to define functions in place:

send_message(sender, priority)

Send a message to a recipient

Parameters:

sender (str) – The person sending the message
priority (int) – The priority of the message, can be a number 1-5

Returns:

the message id

Return type:

int

Raises:

ValueError – if the message_body exceeds 160 characters

Math

There are different ways of highlighting mathematical equations, all of which use LaTeX-based syntax. Equations can be provided inline, for example like this: $a^2 + b^2 = c^2$. Alternatively, it is also possible to provide formulas in a block environment. Option 1 as a directive:

\[ \int (a + b)^{i_j} = \frac{c}{d}\]

and option 2 using the $$ markers:

$$ \sum_{i=0}^\infty i^2 $$

Cards

Some header information

Simple Card Title

Some text that is displayed in a nice card

Footer information

More fullyfledged example from the MyST documentation:

CommonMark-plus

MyST extends the CommonMark syntax specification, to support technical authoring features such as tables and footnotes.

Learn more »

Sphinx compatible

Use the MyST role and directive syntax to harness the full capability of Sphinx, such as admonitions and figures, and all existing Sphinx extensions.

Learn more »

Highly configurable

MyST-parser can be configured at both the global and individual document level, to modify parsing behaviour and access extended syntax features.

Learn more »

Carousels

card 1

card 2

card 3

card 4

card 5

card 6

Buttons

Button text

https://example.com

Tabs

Tabs can be useful if there are multiple ways of doing something, for example if we want to highlight examples in multiple programming languages.

Label1

Content 1

Label2

Content 2

Lua

local openspace = ...
openspace.globebrowsing.goToGeo(123.0, -40.0)

JavaScript

let openspace = ...;
openspace.globebrowsing.goToGeo(123.0, -40.0)

Python

openspace = ...
openspace.globebrowsing.goToGeo(123.0, -40.0)

Diagram

See MermaidJS documentation for more information about the available diagram types

sequenceDiagram Alice ->> Bob: Hello Bob, how are you? Bob-->>John: How about you John? Bob--x Alice: I am good thanks! Bob-x John: I am good thanks! Note right of John: Bob thinks a long<br/>long time, so long<br/>that the text does<br/>not fit on a row. Bob-->Alice: Checking with John... Alice->John: Yes... John, how are you?

graph LR A[Square Rect] -- Link text --> B((Circle)) A --> C(Round Rect) B --> D{Rhombus} C --> D

gitGraph: commit "Ashish" branch newbranch checkout newbranch commit id:"1111" commit tag:"test" checkout main commit type: HIGHLIGHT commit merge newbranch commit branch b2 commit

stateDiagram [*] --> Still Still --> [*] Still --> Moving Moving --> Still Moving --> Crash Crash --> [*]

Glossary

Defining glossary terms that can be used across the entire documentation page. Regardless where the glossary terms are defined, they will be usable on any page.

Some Term: The description what the term means.
Another Term: And another description.
Yet Another Term: And yet another description.

To use it in the text use it like this Sphinx

Section Labels

Some way to specify targets for referencing back to it:

Text text text

Now we can refer back to the previous section reference by inserting it in the text.

Include files

Verbatim include

Include the .gitignore file:

pycache .venv build generated

Include file with syntax highlighting

Raw include

{
  "aaa": {
    "def": 1,
    "ghi": "abc"
  },
  "bbb": [
    1, 2, 3, 4
  ],
  "ccc": false
}

With Caption

With a caption to download

{
  "aaa": {
    "def": 1,
    "ghi": "abc"
  },
  "bbb": [
    1, 2, 3, 4
  ],
  "ccc": false
}

Emphasize lines

{
  "aaa": {
    "def": 1,
    "ghi": "abc"
  },
  "bbb": [
    1, 2, 3, 4
  ],
  "ccc": false
}

Selected lines

Only show selected lines

{
    "def": 1,
    1, 2, 3, 4
  ],
  "ccc": false
}

Kitchen Sink

Markup

Heading without TOC entry

Subscript/Superscript

Abbreviations

Commands

Keystrokes

Menu Selection

Inline comments

Icons embedding

Tables

Markdown-style

MyST style

Multi-column table

Links

Footnotes

Images

Markdown

Centering images

Captions

Dark and Light theme

Videos

Callouts

Sidebar

Markups

Code Highlighting

Default language

Different language

Line number and captions

Highlight lines

Function defintions

Math

Cards

Carousels

Dropdown

No Title

With title

Standard open

Buttons

Tabs

Diagram

Glossary

Section Labels

Include files

Verbatim include

Include file with syntax highlighting

Raw include

With Caption

Emphasize lines

Selected lines