Markdown Files

Whether you write your book’s content in Jupyter Notebooks (.ipynb) or in regular markdown files (.md), you’ll write in the same flavor of markdown called MyST Markdown. This is a simple file to help you get started and show off some syntax.

What is MyST?

MyST stands for “Markedly Structured Text”. It is a slight variation on a flavor of markdown called “CommonMark” markdown, with small syntax extensions to allow you to write roles and directives in the Sphinx ecosystem.

For more about MyST, see the MyST Markdown Overview.

Sample Roles and Directives

Roles and directives are two of the most powerful tools in Jupyter Book. They are kind of like functions, but written in a markup language. They both serve a similar purpose, but roles are written in one line, whereas directives span many lines. They both accept different kinds of inputs, and what they do with those inputs depends on the specific role or directive that is being called.

Here is a “note” directive:

Note

Here is a note

It will be rendered in a special box when you build your book.

Here is an inline directive to refer to a document: Notebooks with MyST Markdown.

Citations

You can also cite references that are stored in a bibtex file. For example, the following syntax: {cite}`holdgraf_evidence_2014` will render like this: [HdHPK14].

Moreover, you can insert a bibliography into your page with this syntax: The {bibliography} directive must be used for all the {cite} roles to render properly. For example, if the references for your book are stored in references.bib, then the bibliography is inserted with:

Gan20

Christopher Gandrud. Reproducible research with R and RStudio. The R series. CRC Press, Boca Raton, FL, third edition edition, 2020. ISBN 978-0-367-14398-5 978-0-367-14402-9.

Guo14

Philip Guo. Python Is Now the Most Popular Introductory Teaching Language at Top ­U.S. ­Universities. July 2014. URL: https://cacm.acm.org/blogs/blog-cacm/176450-python-is-now-the-most-popular-introductory-teaching-language-at-top-us-universities/fulltext (visited on 2022-01-20).

HdHPK14

Christopher Ramsay Holdgraf, Wendy de Heer, Brian N. Pasley, and Robert T. Knight. Evidence for Predictive Coding in Human Auditory Cortex. In International Conference on Cognitive Neuroscience. Brisbane, Australia, Australia, 2014. Frontiers in Neuroscience.

LGMR05

Paul A. Longley, Michael F. Goodchild, David J. Maguire, and David W. Rhind. Geographic Information Systems and Science. Wiley, Chichester ; Hoboken, NJ, 2nd edition edition, March 2005. ISBN 978-0-470-87001-3.

Ola20

Víctor Olaya. Sistemas de Información Geográfica. 2020. URL: https://volaya.github.io/libro-sig/ (visited on 2021-12-31).

Pen11

Roger D. Peng. Reproducible Research in Computational Science. Science, 334(6060):1226–1227, December 2011. Publisher: American Association for the Advancement of Science. URL: https://www.science.org/doi/10.1126/science.1213847 (visited on 2022-04-10), doi:10.1126/science.1213847.

Rob17

David Robinson. The Incredible Growth of Python. September 2017. URL: https://stackoverflow.blog/2017/09/06/incredible-growth-python/ (visited on 2022-01-20).

Sev

Charles Severance. PY4E - Python for Everybody. URL: https://www.py4e.com/ (visited on 2022-01-01).

SSB16

Alex David Singleton, Seth Spielman, and Chris Brunsdon. Establishing a framework for Open Geographic Information science. International Journal of Geographical Information Science, 30(8):1507–1521, August 2016. Publisher: Taylor & Francis _eprint: https://doi.org/10.1080/13658816.2015.1137579. URL: https://doi.org/10.1080/13658816.2015.1137579 (visited on 2022-04-09), doi:10.1080/13658816.2015.1137579.

ZGC13

Pietro Zambelli, Sören Gebbert, and Marco Ciolli. Pygrass: An Object Oriented Python Application Programming Interface (API) for Geographic Resources Analysis Support System (GRASS) Geographic Information System (GIS). ISPRS International Journal of Geo-Information, 2(1):201–219, March 2013. Number: 1 Publisher: Multidisciplinary Digital Publishing Institute. URL: https://www.mdpi.com/2220-9964/2/1/201 (visited on 2022-01-20), doi:10.3390/ijgi2010201.

Learn more

This is just a simple starter to get you started. You can learn a lot more at jupyterbook.org.