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 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: [].

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:

[ASBJ12]

E.S.P. Aradóttir, E.L. Sonnenthal, G. Björnsson, and H. Jónsson. Multidimensional reactive transport modeling of CO$_2$ mineral sequestration in basalts at the hellisheidi geothermal field, iceland. International Journal of Greenhouse Gas Control, 9:24–40, 2012. doi:10.1016/j.ijggc.2012.02.006.

[BB85]

Robert G Berman and Thomas H Brown. Heat capacity of minerals in the system Na2O-K2O-CaO-MgO-FeO-Fe2O3-Al2O3-SiO2-TiO2-H2O-CO2: representation, estimation, and high temperature extrapolation. Contributions to Mineralogy and Petrology, 89:168–183, 1985.

[Got97]

Matthias Gottschalk. Internally consistent thermodynamic data for rock-forming minerals in the system SiO2-TiO2-Al2O3-CaO-MgO-FeO-K2O-Na2O-H2O-CO2. European Journal of Mineralogy, 9(1):175–223, 1997.

[GHP+23]

A.P. Gysi, N.C. Hurtig, R. Pan, G.D. Miron, and D.A. Kulik. Mines thermodynamic database. New Mexico Bureau of Geology and Mineral Resources, 2023. doi:https://doi.org/10.58799/mines-tdb.

[Gys17]

Alexander P. Gysi. Numerical simulations of CO$_2$ sequestration in basaltic rock formations: challenges for optimizing mineral-fluid reactions. Pure and Applied Chemistry, 89:581–596, 2017. doi:10.1515/pac-2016-1016.

[Hel68]

Harold C. Helgeson. Evaluation of irreversible reactions in geochemical processes involving minerals and aqueous solutions—i. thermodynamic relations. Geochimica et Cosmochimica Acta, 32:853–877, 1968. doi:https://doi.org/10.1016/0016-7037(68)90100-2.

[HGM69]

Harold C. Helgeson, Robert M. Garrels, and Fred T. MacKenzie. Evaluation of irreversible reactions in geochemical processes involving minerals and aqueous solutions—ii. applications. Geochimica et Cosmochimica Acta, 33:455–481, 1969. doi:https://doi.org/10.1016/0016-7037(69)90127-6.

[HP98]

TJB Holland and R Powell. An internally consistent thermodynamic data set for phases of petrological interest. Journal of metamorphic Geology, 16(3):309–343, 1998.

[HP11]

TJB Holland and R Powell. An improved and extended internally consistent thermodynamic dataset for phases of petrological interest, involving a new equation of state for solids. Journal of metamorphic Geology, 29(3):333–383, 2011.

[HGM+24]

Nicole C. Hurtig, Alexander P. Gysi, Thomas Monecke, Sven Petersen, and Mark D. Hannington. Tellurium transport and enrichment in volcanogenic massive sulfide deposits: numerical simulations of vent fluids and comparison to modern sea-floor sulfides. Economic Geology, 119:829–851, 2024. doi:10.5382/econgeo.5067.

[HHG18]

Nicole C. Hurtig, Jacob J. Hanley, and Alexander P. Gysi. The role of hydrocarbons in ore formation at the pillara mississippi valley-type zn-pb deposit, canning basin, western australia. Ore Geology Reviews, 102:875–893, 2018. doi:10.1016/j.oregeorev.2018.09.012.

[LKSS17]

Allan MM Leal, Dmitrii A Kulik, William R Smith, and Martin O Saar. An overview of computational methods for chemical equilibrium and kinetic calculations for geochemical and reactive transport modeling. Pure and Applied Chemistry, 89:597–643, 2017. doi:https://doi.org/10.1515/pac-2016-1107.

[LZAZ22]

Peng Lu, Guanru Zhang, John Apps, and Chen Zhu. Comparison of thermodynamic data files for phreeqc. Earth-Science Reviews, 225:103888, 2022. doi:https://doi.org/10.1016/j.earscirev.2021.103888.

[OBP09]

Eric H Oelkers, Pascale Benezeth, and Gleb S Pokrovski. Thermodynamic databases for water-rock interaction. Reviews in Mineralogy and Geochemistry, 70(1):1–46, 2009.

[PGM18]

Samuel Pierre, Alexander P. Gysi, and Thomas Monecke. Fluid chemistry of mid-ocean ridge hydrothermal vents: a comparison between numerical modeling and vent geochemical data. Geofluids, 2018:1–20, 2018. doi:10.1155/2018/1389379.

[ZZL+16]

Kurt Zimmer, Yilun Zhang, Peng Lu, Yanyan Chen, Guanru Zhang, Mehmet Dalkilic, and Chen Zhu. Supcrtbl: a revised and extended thermodynamic dataset and software package of supcrt92. Computers & geosciences, 90:97–111, 2016. doi:https://doi.org/10.1016/j.cageo.2016.02.013.

Learn more

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