Markdown is widely used in blogging, instant messaging, online forums, collaborative software, documentation pages, and readme files. Since the initial description of Markdown 10 contained ambiguities and unanswered questions, the implementations that appeared over the years have subtle differences and many come with syntax extensions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email. The best way to get a feel for Markdown’s formatting syntax is simply to look at a Markdown-formatted document. You should see the file you created, test1.md. To convert it to HTML, use this command: pandoc test1.md -f markdown -t html -s -o test1.html. The filename test1.md tells pandoc which file to convert. The -s option says to create a “standalone” file, with a header and footer, not just a fragment. And the -o test1.html says to put the output. Markdown is a plain-text file format. The extensions.md and.markdown are just text files written in Markdown syntax. If you have a Readme.md in your repo, GitHub will show the contents on the home page of your repo.
You can write content in regular Markdown files (e.g., files ending in
.md
).Jupyter Book supports any Markdown syntax that is supported by Jupyter notebooks.Jupyter Notebook Markdown is an extension of a flavour of Markdown calledCommonMark Markdown.It has many elements for standard text processing, though it lacks a lot of features used forpublishing and documentation.Note
If you’d like a more in-depth overview and guide to CommonMark Markdown, seethe CommonMark Markdown tutorial.
This page describes some basic features of the Jupyter Notebook Markdown, and how toinclude them with your book.
![Md File Syntax Md File Syntax](/uploads/1/1/7/7/117769821/256671942.png)
Embedding media¶
Adding images¶
You can reference external media like images from your Markdown file. If you userelative paths, then they will continue to work when the Markdown files are copied over,so long as they point to a file that’s inside of the repository.
Here’s an image relative to the book content root
![Syntax Syntax](https://db.yihui.name/imgur/9YlzL.png)
It was generated with this code:
See also
Md File Link Syntax
Images and figures for more information.
Adding movies¶
You can even embed references to movies on the web! For example, here’s a little GIF for you!
This will be included in your book when it is built.
Mathematics¶
For HTML outputs, Jupyter Book uses the excellent MathJax library,along with the default Jupyter Notebook configuration, for rendering mathematics from LaTeX-style syntax.
For example, here’s a mathematical expression rendered with MathJax:
[begin{split}P(A_1 cup A_2 cup A_3)& = P(B cup A_3) & = P(B) + P(A_3) - P(BA_3) &= P(A_1) + P(A_2) - P(A_1A_2) + P(A_3) - P(A_1A_3 cup A_2A_3) &= sum_{i=1}^3 P(A_i) - mathop{sum sum}_{1 le i < j le 3} P(A_iA_j) + P(A_1A_2A_3)end{split}]
Block-level mathematics¶
You can include block-level mathematics by wrapping your formulas in
$$
characters.For example, the following block:Results in this output:
[wow = its^{math}]
You can also include math blocks by using LaTeX-style syntax using
begin{align*}
.For example, the following block:Results in:
[begin{align*}yep = its_{more}^{math}end{align*}]
Important
Md File Syntax
This requires the
amsmath
MyST extension to be enabled.Md File Syntax New Line
Extended Markdown with MyST Markdown¶
Md File Code Snippet
In addition to CommonMark Markdown, Jupyter Book also supports a more fully-featured version of Markdown called MyST Markdown.This is a superset of CommonMark that includes syntactic pieces that are useful for publishing computational narratives.For more information about MyST Markdown, see MyST Markdown overview.