Guide: From LaTeX to Sphinx with MyST Markdown

1. Guide: From LaTeX to Sphinx with MyST Markdown#

We write in MyST Markdown, which is a hybrid of standard Markdown (for speed) and LaTeX (for math/referencing). Sphinx use reStructuredText (.rst) by default but we will use MyST Markdown (.md) (derived from Markdown) which is closer to LaTeX;

Check out the MyST Documentation: https://mystmd.org/ and Sphinx Documentation: https://www.sphinx-doc.org/en/master/index.html for in detailed guides.

1.1. Structure and headers#

Instead of \section and \subsection, use hashes #.

# Title (Part)
## Section
### Subsection

1.2. Mathematics#

We use MathJax. You can paste your existing LaTeX code almost directly.

1.2.1. Inline math#

Works exactly like LaTeX. Use single dollar signs or {math}`\alpha` .

  • Write: The parameter $\alpha$ must be $> 0$.

  • Result: The parameter \(\alpha\) must be \(> 0\).

1.2.2. Numbered equations#

In LaTeX, you used \begin{equation} ... \end{equation}. In MyST, use the math directive.

Write this:

```{math}
:label: eq-navier-stokes
\rho \left( \frac{\partial \mathbf{v}}{\partial t} + \mathbf{v} \cdot \nabla \mathbf{v} \right) = -\nabla p + \mu \nabla^2 \mathbf{v} + \mathbf{f}
```

Result: It will render the equation centered and assign it a number automatically.

(1.1)#\[\rho \left( \frac{\partial \mathbf{v}}{\partial t} + \mathbf{v} \cdot \nabla \mathbf{v} \right) = -\nabla p + \mu \nabla^2 \mathbf{v} + \mathbf{f}\]

1.3. Cross-referencing#

We can link to anything, anywhere in the project.

1.3.1. Referencing equations#

Instead of \ref{eq:label}, use {eq} or [](#target).

  • Write: As seen in {eq}`eq-navier-stokes` or [](#eq-navier-stokes)...

  • Result: As seen in (1.1) or (1.1)…

1.3.2. Referencing sections#

To link to a section, you must first place a target label right above the header.

Step 1: Define the target

(results-section)=
## Simulation results

Step 2: Link to it

  • Write: See the {ref}`my-results-section` for...

  • Result: “See the Simulation Results for…”

1.4. Callouts (Admonitions)#

Sphinx allows specialized boxes for notes or warnings.

```{note}
This is a note.
```

Note

This is a note.

```{warning}
This is a very important warning.
```

Warning

This is a very important warning.

1.5. Images and figures#

In LaTeX, you use \begin{figure}. In MyST, we use the {figure} directive.

1.5.1. Inserting an image#

You must place the image file inside the source/ folder. It can be in a subdirectory, here it is in source/FIG/ subdir.

```{figure} FIG/Figure1_130528_v2.png
:name: fig-orchidee
:width: 80%
:align: center

This is the caption. 
```
_images/Figure1_130528_v2.png

Fig. 1.1 This is the caption.#

1.5.2. Referencing the image#

Just like equations, we use the label defined in :name:.

  • You Write: See Figure {numref}`fig-orchidee` .

  • Result: See Figure Fig. 1.1.

Note

We use {numref} instead of {ref} for figures if we want it to say “Figure 1” automatically instead of just the link title.

1.6. Footnotes#

We use the standard bracket-caret syntax.

Option A: Named Labels Use words instead of numbers so you don’t have to re-number them later.

  • Text: The model use a Gaussian approach[^gaussian-ref].

  • Bottom: [^gaussian-ref]: See Xyz et al, 2024. The model use a Gaussian approach[1].

Option B: Inline Write the note directly inside the text.

  • Text: The parameter is small^[Specifically less than 1e-6]. This statement has a note attached^[This is the content of the footnote, written inline.].

Option C: Margin note

```{margin}
Here is a paragraph of text.
**Note:** This text will appear in the right margin next to the paragraph!
```

Here is a paragraph of text.

1.7. Citations (Bibliography)#

We use a standard .bib file (source/refs.bib).

1.7.1. Citing in text#

  • You Write: Relativity was a breakthrough {cite}`einstein1905`.

  • Result: Relativity was a breakthrough [1].

  • Multiple: Physics is fun {cite}`einstein1905,feynman1963`.

  • Result: Physics is fun [1, 2].

1.7.2. The references list#

We place this at the very bottom of the document or in a dedicated “References” chapter.

# References
```{bibliography}
```
Contents