A text file can only be used to store unformatted text. The markdown file is similar to a text file, however allows text to be formatted using very simple markdown syntax. The Markdown syntax is also used for markdown cells in Interactive Python Notebooks. In a notebook file, markdown cells are commonly used to create documentation around code, in a similar form to a scientific paper.
Text can be enclosed in stars * or tildes ~ to format it. One set of stars * makes text italic, two sets of stars * makes it bold and three sets of stars * makes it bold-italic. Two sets of tildes ~ make it strike-through.
The following markdown:
Let's make a sentence with *italic text*, **bold text**, ***bold-italic*** and ~~strike-through~~ text.Produces:
Let's make a sentence with italic text, bold text, bold-italic and strike-through text.
When one of the formatting characters is required in the text, it needs to be prepended with the left slash \ to insert an escape character. For example to insert the left slash itself, \ two left slashes are used \\ where the first left slash \ denotes insertion of an escape character and the second left slash \ denotes the escape character to be inserted is the left slash itself\. The following markdown:
Let's make a sentence with \*italic text\*, \*\*bold text\*\*, \*\*\*bold-italic\*\*\* and \~\~strike-through\~\~ text.
\\Produces:
Let's make a sentence with *italic text*, **bold text**, ***bold-italic*** and ~~strike-through~~ text. \
Headings can be created by prefixing the text of a heading with a #. Increasing the number of # increases the Heading Level. The following markdown:
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
Produces:
Each heading will display on the markdown files table of contents.
For convenience a long sentence written over multiple lines is formatted as a single sentence. The following markdown:
She sells
seashells
on the
seashoreProduces:
She sells seashells on the seashore
If instead the sentence is to be deliberately separated out over different lines, doubly space it. The following markdown:
She sells
seashells
on the
seashore
Produces:
She sells
seashells
on the
seashore
Bullet points can be created by prepending each line with a star* (but not ending with a star as recall that would make the text italic) or prepending each line with 1., 2. and so on for a numbered list.
The following markdown:
Bullet Point List
* one
* two
* three
Bullet Point List (spaced)
* one
* two
* three
Numeric List
1. one
2. two
3. three
Numeric List (spaced)
1. one
2. two
3. three
Produces:
Bullet Point List
- one
- two
- three
Bullet Point List (spaced)
-
one
-
two
-
three
Numeric List
- one
- two
- three
Numeric List (spaced)
-
one
-
two
-
three
The pipe | is used to seperate columns out in a table. The table is constructed row by row. The first row consists of the column names and the second row is the column alignment format specification (which can be changed to normal ---, left aligned :-, right aligned -:, left-aligned with title centred :-:). All subsequent rows are rows containing table data.
The following markdown:
|num|number|
|---|---|
|1|one|
|2|two|
|3|three|
|num|number|
|---|:-|
|1|one|
|2|two|
|3|three|
|num|number|
|---|-:|
|1|one|
|2|two|
|3|three|
|num|number|
|---|:-:|
|1|one|
|2|two|
|3|three|Produces:
| num | number |
|---|---|
| 1 | one |
| 2 | two |
| 3 | three |
| num | number |
|---|---|
| 1 | one |
| 2 | two |
| 3 | three |
| num | number |
|---|---|
| 1 | one |
| 2 | two |
| 3 | three |
| num | number |
|---|---|
| 1 | one |
| 2 | two |
| 3 | three |
An empty line with --- will produce a separator.
The following code:
---Produces the separator line between the two arrows:
↓
↑
To include code in a markdown file begin and end the code with 3 back-quotes ```. The following markdown:
The code is ```print('Hello World!')```
Produces:
The code is print('Hello World!')
3 back quotes ``` on a new line can be used to begin and end a code-block.
The following markdown:
```
print('Hello World!')
print('Goodbye World!')
```
Produces:
print('Hello World!')
print('Goodbye World!')
To apply the correct syntax highlighting for the programming language, the programming language should be specified after the opening ```
The following markdown:
```python
print('Hello World!')
print('Goodbye World!')
```
Produces:
print('Hello World!')
print('Goodbye World!')Other programming languages can be specified using markdown. Such as
markdown:
```markdown
Let's make a sentence with \*italic text\*, \*\*bold text\*\*, \*\*\*bold-italic\*\*\* and \~\~strike-through\~\~ text.
\\
```
Let's make a sentence with \*italic text\*, \*\*bold text\*\*, \*\*\*bold-italic\*\*\* and \~\~strike-through\~\~ text.
\\cmd:
```cmd
cd "C:\Windows\System32"
```
cd "C:\Windows\System32"powershell:
```powershell
cd "~\miniforge3"
```
cd "~\miniforge3"There is the abbreviation ps1 (ps is another programming language postscript) however ps1 is not as widely recognised as powershell by markdown renderers.
bash:
```bash
cd "~/miniforge3"
```
cd "~/miniforge3"tex:
```tex
$\sin{\alpha}\pm\sin{\beta}=2\sin{\frac{1}{2}\left(\alpha\pm\beta\right)}\cos{\frac{1}{2}\left(\alpha\mp\beta\right)}$
```
$\sin{\alpha}\pm\sin{\beta}=2\sin{\frac{1}{2}\left(\alpha\pm\beta\right)}\cos{\frac{1}{2}\left(\alpha\mp\beta\right)}$json:
```json
{
"preferences": {
"default_formatter": {
"python": ["autopep8", "isort", "black"],
"R": ["styler", "formatR"],
}
}
}
```
{
"preferences": {
"default_formatter": {
"python": ["autopep8", "isort", "black"],
"R": ["styler", "formatR"],
}
}
}To include the ``` themselves as part of the markdown text. Enclose the three back quotes ``` in four backquotes ````. To get 4 backquotes (enclose in 5 backquotes). The following markdown:
````
```
````
Produces:
```
Links can be inserted using the syntax []() where the square brackets are used to enclose the link name and the parenthesis are used to enclose the link address.
If the link is an image this may be prepended with an exclamation mark ![]() which will display the image within the markdown file.
The following markdown:
[Bytes](https://github.com/PhilipYip1988/python-tutorials/blob/main/markdown/images/img_001.png)Produces:
The following markdown:
Produces:
If the Image can't be found, the information provided in the square brackets displays.
If the image is in the same folder as the markdown file. The file name can be specified directly.
In the file path ./ can be used to specify a subfolder and ../ can be used to go up a level. The img_001.png in the subfolder images can be selected for example using the following markdown:
Producing:
Note some programs will save to .PNG and others will save to .png by default.
It is recommended to enable file extensions for known file types and ensure all file extensions are in lower case.
GitHub for example seems to be sensitive regarding the case of the file extension and won't render properly if the file has a file extension that uses a different case. By enabling the file extension the case of each file extension can be examined.
To specify the width of an image, HTML can instead be used:
<img src='./images/img_001.png' alt='Bytes' width='400'/>
<img src='./images/img_001.png' alt='Bytes' width='300'/>
<img src='./images/img_001.png' alt='Bytes' width='200'/>
The markdown file supports TeX and this can be used for both Inline and Display Equations.
Inline Equation:
$EQUATION$Display Equation:
$$EQUATION$$Inline Equation example:
$\sin{\alpha}\pm\sin{\beta}=2\sin{\frac{1}{2}\left(\alpha\pm\beta\right)}\cos{\frac{1}{2}\left(\alpha\mp\beta\right)}$Display Equation example:
$$\sin{\alpha}\pm\sin{\beta}=2\sin{\frac{1}{2}\left(\alpha\pm\beta\right)}\cos{\frac{1}{2}\left(\alpha\mp\beta\right)}$$Only Office Desktop Editors is a free cross-platform office suite developed on GitHub. GitHub: Only Office Desktop Editors. On Ubuntu a snap package is available in Ubuntu software. It has an equation editor that can be used to visually construct an equation. The constructed equation can be converted to Linear using LaTeX. Markdown uses teX which is a subset of LaTeX. In most cases the equation can be used directly in a Markdown Document or modified slightly:
The equation editor in Microsoft Word is similar.
TeX should be insensitive with spacing and newlines:
$$\left[\begin{matrix}a\\b\\c\end{matrix}\right]$$However the TeX renderer on GitHub has bugs and this does not render unless it is spaced out over multiple lines:
$$ \begin{bmatrix}
a \\
b \\
c \\
\end{bmatrix} $$The same issue occurs with matrices:
$$ \begin{bmatrix}
a & b & c \\
d & e & f \\
g & h & i \\
\end{bmatrix} $$In Microsoft Word, the trigonometric identities use additional LaTeX syntax:
$\sin\funcapply(x)$This needs to be simplified into TeX in order to render properly:
$\sin(x)$The following characters are reserved symbols as they are used as formatting characters in TeX:
| Symbol Name | Symbol | Meaning |
|---|---|---|
| dollar sign | $ |
enclosure for math mode; single enclosure=inline equation, double enclosure=display equation |
| single quotes | ' |
used for str |
| double quotes | " |
used for str |
| backslash | \ |
inserts an escape character or command |
| braces | {} |
enclose command arguments |
| ampersand | & |
group command arguments |
| hash | # |
used for a reference |
| percentage sign | % |
comment |
| pipe | | |
column divider |
| hyphen | - |
minus symbol |
| caret | ^ |
superscript |
| underscore | _ |
subscript |
| tilde | ~ |
non-breaking space |
The following commands can be used to change the text type:
| description | TeX | output |
|---|---|---|
| math text | $Hello World! 1-2$ |
|
| math roman | $\mathrm{Hello World! 1-2}$ |
|
| bold text | $\textbf{Hello World! 1-2}$ |
|
| normal text | $\text{Hello World! 1-2}$ |
|
| verbatim text | $\verb|{"Hello World!" 1-2 ~^\}|$ |
Notice a command is of the form:
\command{arg}Sometimes the formatting characters need to be incorporated into the equation. This can be done using the escape characters:
| description | TeX | output |
|---|---|---|
| dollar sign | $\$$ |
$$$ |
| percentage sign | $\%$ |
|
| hash | $\#$ |
|
| ampersand | $\&$ |
However the TeX renderer on GitHub does not process these correctly. The above display correctly in VSCode and JupyterLab.
Using verbose can often yield better results however cannot be used for the dollar sign itself:
$\verb|%|$
$\verb|#|$
$\verb|&|$Some of the other formatting characters can be inserted using the following syntax:
| description | TeX | output |
|---|---|---|
| backslash | $\backslash$ |
|
| pipe | $\vert$ |
|
| left brace | $\lbrace$ |
|
| right brace | $\rbrace$ |
This syntax is also available for commonly used mathematical symbols:
| description | TeX | output |
|---|---|---|
| equal to | $=$ |
|
| equivalent to | $\equiv$ |
|
| not equal to | $\ne$ |
|
| similar to | $\sim$ |
|
| approximate to | $\approx$ |
|
| tilde | $\sim$ |
|
| approximately equal to | $\cong$ |
|
| plus | $+$ |
|
| minus | $-$ |
|
| plus minus | $\pm$ |
|
| minus plus | $\mp$ |
|
| asterisk | $\ast$ |
|
| times | $\times$ |
|
| centre dot | $\cdot$ |
|
| period | $.$ |
|
| bullet | $\bullet$ |
|
| colon | $\colon$ |
|
| centre dots | $\cdots$ |
|
| vertical dots | $\vdots$ |
|
| therefore | $\therefore$ |
|
| division slash | $/$ |
|
| division sign | $\div$ |
|
| less than | $<$ |
|
| less than or equal to | $\leq$ |
|
| greater than | $>$ |
|
| greater than or equal to | $\geq$ |
|
| factorial | $!$ |
|
| degree | $\degree$ |
|
| infinity | $\infty$ |
|
| proportional to | $\propto$ |
|
| partial | $\partial$ |
|
| hbar | $\hbar$ |
|
| union | $\cup$ |
|
| intersection | $\cap$ |
|
| emptyset | $\emptyset$ |
|
| exists | $\exists$ |
|
| in | $\in$ |
|
| not in | $\notin$ |
|
| ni | $\ni$ |
|
| left arrow | $\leftarrow$ |
|
| right arrow | $\rightarrow$ |
|
| left right arrow | $\leftrightarrow$ |
|
| up arrow | $\uparrow$ |
|
| down arrow | $\uparrow$ |
|
| up down arrow | $\updownarrow$ |
The Greek letters are commonly used in physics:
| description | TeX | output |
|---|---|---|
| alpha | $\alpha$ |
|
| beta | $\beta$ |
|
| Gamma | $\Gamma$ |
|
| gamma | $\gamma$ |
|
| Delta | $\Delta$ |
|
| delta | $\delta$ |
|
| nabla | $\nabla$ |
|
| epsilon | $\epsilon$ |
|
| epsilon | $\varepsilon$ |
|
| zeta | $\zeta$ |
|
| eta | $\eta$ |
|
| kappa | $\kappa$ |
|
| Lambda | $\Lamba$ |
|
| mu | $\mu$ |
|
| Xi | $\Xi$ |
|
| xi | $\xi$ |
|
| Pi | $\Pi$ |
|
| pi | $\pi$ |
|
| rho | $\rho$ |
|
| Sigma | $\Sigma$ |
|
| sigma | $\sigma$ |
|
| sigma | $\varsigma$ |
|
| tau | $\tau$ |
|
| Upsilon | $\Upsilon$ |
|
| upsilon | $\upsilon$ |
|
| Phi | $\Phi$ |
|
| phi | $\phi$ |
|
| chi | $\chi$ |
|
| Psi | $\Psi$ |
|
| psi | $\psi$ |
|
| Omega | $\Omega$ |
|
| omega | $\omega$ |
Note the Greek letters A, B, E, Z, H, I, i, K, M, N, O, o and P that are the same as Latin letters are therefore just represented using the Latin letters.
The following commands can be used to apply an accent or trigonometric identity:
| description | TeX | output |
|---|---|---|
| math text with dot | $\dot{x}$ |
|
| math text with double dot | $\ddot{x}$ |
|
| math text with bar | $\bar{x}$ |
|
| math text with hat | $\hat{x}$ |
|
| math text with arrow vector | $\vec{x}$ |
|
| math text with tilde | $\tilde{x}$ |
|
| math text with wide tilde | $\widetilde{xx}$ |
|
| math text with check | $\check{x}$ |
|
| math text with acute | $\acute{x}$ |
|
| math text with grave | $\grave{x}$ |
|
| math text with breve | $\breve{x}$ |
|
| subscript | $x_{2}$ |
|
| superscript | $x^{3}$ |
|
| subscript and superscript | $x_{2}^{3}$ |
|
| square root | $\sqrt{x}$ |
|
| sin | $\sin{x}$ |
|
| cos | $\cos{x}$ |
|
| tan | $\tan{x}$ |
|
| log | $\log{x}$ |
|
| exp | $\exp{x}$ |
Fractions can be added using:
| description | LaTeX | output |
|---|---|---|
| inline fraction | $\frac{a}{b}$ |
|
| display fraction | $$\frac{a}{b}$$ |
| description | TeX | output |
|---|---|---|
| inline fraction parenthesis | $(\frac{a}{b})$ |
|
| display fraction parenthesis | $$(\frac{a}{b})$$ |
|
| display fraction parenthesis automatic size | $$\left(\frac{a}{b}\right)$$ |
|
| inline fraction square | $[\frac{a}{b}]$ |
|
| display fraction square | $$[\frac{a}{b}]$$ |
|
| display fraction square automatic size | $$\left[\frac{a}{b}\right]$$ |
|
| inline fraction braces | $\lbrace\frac{a}{b}\rbrace$ |
|
| display fraction braces | $$\lbrace\frac{a}{b}\rbrace$$ |
|
| display fraction braces automatic size | $$\left\lbrace\frac{a}{b}\right\lbrace$$ |
Prefixing \left and \right to a set of brackets will automatically resize the brackets.
Vectors and matrices only work as display equations. The \begin and \end commands are used to enclose the matrix:
$$ \begin
\end $$The type of matrix is supplied as an input argument for both commands, recall that the {} is used to enclose input arguments:
$$ \begin{bmatrix}
\end{bmatrix} $$Row Vectors use & as a delimiter to move onto the new column and are typically input on a single line:
$$ \begin{bmatrix}
a&b&c
\end{bmatrix} $$Note that spacing can be used for readability and is not processed in math mode so the above can be written using the following and displays identically:
$$ \begin{bmatrix}
a & b & c
\end{bmatrix} $$$$ \begin{bmatrix}
a & b & c
\end{bmatrix} $$Column Vectors use the symbol \ as a delimiter to move onto the next row. However in TeX \ is an instruction to insert an escape character, therefore to insert the escape character \ itself \\ must be used. The TeX for a column vector and matrix should be insensitive to spacing however does not render properly on GitHub without spacing and newlines:
$$ \begin{bmatrix}
a \\
b \\
c \\
\end{bmatrix} $$Matrices use & as a delimiter to move onto the new column and \ as a delimiter to move onto the next row and are input over multiple lines:
$$ \begin{bmatrix}
a & b & c \\
c & d & d \\
e & f & g \\
\end{bmatrix} $$The matrix kind matrix has no brackets:
$$ \begin{matrix}
a & b & c \\
c & d & d \\
e & f & g \\
\end{matrix} $$The matrix kind bmatrix has square brackets:
$$ \begin{bmatrix}
a & b & c \\
c & d & d \\
e & f & g \\
\end{bmatrix} $$The matrix kind pmatrix has parenthesis:
$$ \begin{pmatrix}
a & b & c \\
c & d & d \\
e & f & g \\
\end{pmatrix} $$The matrix kind vmatrix has vertical brackets
$$ \begin{vmatrix}
a & b & c \\
c & d & d \\
e & f & g \\
\end{vmatrix} $$To make a sum use:
$\sum{x}$An underscore _ can be used to add a subscript to the sum:
$\sum_{l}{x}$Notice that the order here matters:
$\sum{x}_{l}}$Quite often text will be provided as an subscript. Notice that two commands are stacked i.e. \text{lower} is the input argument for the command _
$\sum_{\text{lower}}{x}$A hat ^ can be used to add a subscript enclosed in braces:
$\sum^{\text{upper}}{x}$Use of both a subscript and superscript often doesn't render well for inline equations.
$\sum_{\text{lower}}^{\text{upper}}{x}$And therefore a display equation can be used:
$$\sum_{\text{lower}}^{\text{upper}}{x}$$To make an integral use:
$\int$A display equation should be used for an integral, if limits are added:
$$\int_{\text{lower}}^{\text{upper}}{x}$$For a double integral, triple integral and integral over a close lined use:
$$\iint_{\text{lower}}^{\text{upper}}{x}$$
$$\iiint_{\text{lower}}^{\text{upper}}{x}$$
$$\oint_{\text{lower}}^{\text{upper}}{x}$$To make an product or coproduct use:
$$\prod_{\text{lower}}^{\text{upper}}{x}$$
$$\amalg_{\text{lower}}^{\text{upper}}{x}$$To make a Union or Intersection use:
$$\bigcup_{\text{lower}}^{\text{upper}}{x}$$
$$\bigcap_{\text{lower}}^{\text{upper}}{x}$$To make a "logical or" and "logical and" use:
$$\bigvee_{\text{lower}}^{\text{upper}}{x}$$
$$\bigwedge_{\text{lower}}^{\text{upper}}{x}$$