---

orphan: true

Markdown in Sphinx Tips and Tricks

In this repository, you can use both markdown and reSTructuredText to author your content. This section lists most common examples of how you can use Sphinx directives in your markdown files to expand your contributions. For more information, see MyST Parser Documentation and reSTructuredText to Markdown mapping.

Admonitions

Here is an example of how you can add a note. Similarly, you can add {tip} and {warning}.

::::{tab-set}

:::{tab-item} Example

:alt: note
:class: bg-primary
:width: 210px
:align: center

:::

:::{tab-item} Source

:alt: note
:class: bg-primary
:width: 170px
:align: center

:::

::::

Images

This page has extensive reference on how to add an image. You can use the standard markdown syntax as well as an extended one that allows you to modify width, alignment, and other parameters of an image.

::::{tab-set}

:::{tab-item} Standard syntax

![image example][/_static/img/example-image.png]

:::

:::{tab-item} Extended Syntax

```{image} img/s_demo_note_source.png
:alt: example
:class: bg-primary
:width: 150px
:align: center
```

:::

::::

Code Block

You can use standard code blocks as well as the extended syntax and include the code from other files as. More information can be found on this page. Examples:

::::{tab-set}

:::{tab-item} Standard syntax

```python
a = 1
b = 2
c = a + b
print(c)
```

:::

:::{tab-item} Output

a = 1
b = 2
c = a + b
print(c)

:::

::::

::::{tab-set}

:::{tab-item} Extended Syntax

```{code-block} python
:caption: My example code
:emphasize-lines: 4
:lineno-start: 1

a = 1
b = 2
c = a + b
print(c)
```

:::

:::{tab-item} Output

:caption: My example code
:emphasize-lines: 4
:lineno-start: 1

a = 1
b = 2
c = a + b
print(c)

:::

::::

::::{tab-set}

:::{tab-item} Include from other files Here is how you can include the code from another file. In this example, we will only include the code between the start-after and end-before markers.

```{literalinclude} _static/example.py
:start-after: start
:end-before: end
```

The example.py file looks like this:

:emphasize-lines: 10, 16
"""
A sample python file
"""

class Person:
    def __init__(self, name, age):
        self.name = name
        self.age = age

    # start

    def introduce(self):
        print("Hello, my name is", self.name)
        print("I am", self.age, "years old")

    # end

person = Person("Alice", 25)
person.introduce()
:::

:::{tab-item} Output
```{literalinclude} _static/example.py
:start-after: start
:end-before: end

::: ::::