MyST Markdown Syntax Sample

MyST Markdown Syntax Sample#

This page demonstrates MyST Markdown syntax using examples that correspond to the RST quick reference guide. This serves as a practical example of how to write Open edX documentation using MyST Markdown.

Section Structure Example#

This demonstrates how to structure content with multiple heading levels and sections.

Subsection Example#

Content for this subsection to demonstrate heading hierarchy.

Another Subsection#

More content to show section organization.

Inline Markup Demonstration#

This section shows various bold formatting, italic text, and mono-spaced code snippets. You can also create GUI elements that stand out in the documentation.

Lists and Organization#

You can create both numbered and bulleted lists:

  1. First ordered item

    • Sub-item under first item

    • Another sub-item

  2. Second ordered item

Here’s an unordered list:

  • First bullet point

    1. Numbered sub-item

    2. Another numbered sub-item

  • Second bullet point

Linking Examples#

Directives and Admonitions#

MyST Markdown supports many useful directives:

Warning

This is a warning directive.

It will be styled to stand out in the documentation.

Note

This is a note directive.

It will stand out but not as much as a warning.

See also

Open edX Documentation : Link to the main documentation site

MyST Parser Documentation : Complete MyST Markdown documentation

Code Examples#

Here’s a Python code block:

def hello_world():
    """A simple function demonstration."""
    print("Hello, Open edX documentation!")
    return True

And here’s some generic code:

Generic code block without syntax highlighting.
Could be configuration files or pseudo-code.

Images and Media#

Open edX Logo

Tables#

Here’s a simple table in Markdown format:

Feature

RST

MyST Markdown

Headings

Underlines with symbols

Hash symbols (#)

Bold text

**bold**

**bold**

Code blocks

.. code-block::

```language

Directives

.. directive::

```{directive}

Sidebars and Special Content#

Substitutions#

MyST Markdown supports substitutions just like RST. These would be defined in the substitutions.txt file:

A line of text with a |Platform name| substitution inserted.

Advanced Features#

Tab Sets (like in the quick reference)#

This is content for the first tab.

# Python code in tab A
print("Tab A content")

This is content for the second tab.

// JavaScript code in tab B
console.log("Tab B content");

Complex Nested Content#

Note

This note contains nested content:

  1. A numbered list item

    # Code within a list within a note
def nested_example():
    return "Complex nesting works!"

  2. Another item with bold and italic text

    Warning

    Even warnings can be nested inside notes!

Conclusion#

This sample demonstrates the key MyST Markdown features available for Open edX documentation. The syntax is clean, readable, and powerful enough to handle complex documentation needs while remaining approachable for new contributors.

Maintenance Chart

Review Date

Working Group Reviewer

Release

Test Situation

Contents