1--- 2orphan: true 3--- 4# Markdown in Sphinx Tips and Tricks 5 6In this repository, you can use both markdown and reSTructuredText to author 7your content. This section lists most common examples of how you can use 8Sphinx directives in your markdown files to expand your contributions. 9For more information, see 10[MyST Parser Documentation](https://myst-parser.readthedocs.io/en/v0.17.1/sphinx/intro.html) 11and [reSTructuredText to Markdown mapping](https://myst-parser.readthedocs.io/en/v0.17.1/syntax/syntax.html#syntax-directives). 12 13## Admonitions 14 15Here is an example of how you can add a note. Similarly, you can add 16`{tip}` and `{warning}`. 17 18::::{tab-set} 19 20:::{tab-item} Example 21```{image} /_static/img/s_demo_note_render.png 22:alt: note 23:class: bg-primary 24:width: 210px 25:align: center 26``` 27::: 28 29:::{tab-item} Source 30```{image} /_static/img/s_demo_note_source.png 31:alt: note 32:class: bg-primary 33:width: 170px 34:align: center 35``` 36::: 37 38:::: 39 40## Images 41 42[This page](https://myst-parser.readthedocs.io/en/latest/syntax/images_and_figures.html) 43has extensive reference on how to add an image. You can use the standard markdown 44syntax as well as an extended one that allows you to modify width, alignment, and 45other parameters of an image. 46 47::::{tab-set} 48 49:::{tab-item} Standard syntax 50```{code-block} 51![image example][/_static/img/example-image.png] 52``` 53::: 54 55:::{tab-item} Extended Syntax 56````{code-block} 57```{image} img/s_demo_note_source.png 58:alt: example 59:class: bg-primary 60:width: 150px 61:align: center 62``` 63```` 64::: 65 66:::: 67 68## Code Block 69 70You can use standard code blocks as well as the extended syntax and 71include the code from other files as. More information can be 72found on [this page](https://myst-parser.readthedocs.io/en/latest/syntax/code_and_apis.html). 73Examples: 74 75::::{tab-set} 76 77:::{tab-item} Standard syntax 78````{code-block} 79```python 80a = 1 81b = 2 82c = a + b 83print(c) 84``` 85```` 86::: 87 88:::{tab-item} Output 89```python 90a = 1 91b = 2 92c = a + b 93print(c) 94``` 95::: 96 97:::: 98 99::::{tab-set} 100 101:::{tab-item} Extended Syntax 102````{code-block} 103```{code-block} python 104:caption: My example code 105:emphasize-lines: 4 106:lineno-start: 1 107 108a = 1 109b = 2 110c = a + b 111print(c) 112``` 113```` 114::: 115 116:::{tab-item} Output 117```{code-block} python 118:caption: My example code 119:emphasize-lines: 4 120:lineno-start: 1 121 122a = 1 123b = 2 124c = a + b 125print(c) 126``` 127::: 128 129:::: 130 131::::{tab-set} 132 133:::{tab-item} Include from other files 134Here is how you can include the code from another file. 135In this example, we will only include the code between 136the `start-after` and `end-before` markers. 137 138````{code-block} 139```{literalinclude} _static/example.py 140:start-after: start 141:end-before: end 142``` 143```` 144The `example.py` file looks like this: 145```{code-block} python 146:emphasize-lines: 10, 16 147""" 148A sample python file 149""" 150 151class Person: 152 def __init__(self, name, age): 153 self.name = name 154 self.age = age 155 156 # start 157 158 def introduce(self): 159 print("Hello, my name is", self.name) 160 print("I am", self.age, "years old") 161 162 # end 163 164person = Person("Alice", 25) 165person.introduce() 166::: 167 168:::{tab-item} Output 169```{literalinclude} _static/example.py 170:start-after: start 171:end-before: end 172``` 173::: 174:::: 175
