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: [Holdgraf et al., 2014].

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:

[ALMK16]

Julia Angwin, Jeff Larson, Surya Mattu, and Lauren Kirchner. Machine bias: there's software used across the country to predict future criminals. and it's biased against blacks. ProPublica, mayo 2016. URL: https://www.propublica.org/article/machine-bias-risk-assessments-in-criminal-sentencing.

[Bel43]

Andrés Bello. Discurso pronunciado en la instalación de la universidad de chile. Discurso inaugural, septiembre 1843. Discurso fundacional de la Universidad de Chile. URL: https://uchile.cl/presentacion/historia/discurso-inaugural.

[BKL09]

Steven Bird, Ewan Klein, and Edward Loper. Natural Language Processing with Python: Analyzing Text with the Natural Language Toolkit. O'Reilly Media, Sebastopol, CA, 2009. ISBN 978-0596516499. URL: https://www.nltk.org/book/.

[Bla20]

Elisenda Blasi. La huella digital: qué es y cómo protegerla. 2020. Artículo sobre identidad digital y privacidad. URL: https://www.uoc.edu/portal/es/news/actualitat/2020/.

[BG18]

Joy Buolamwini and Timnit Gebru. Gender shades: intersectional accuracy disparities in commercial gender classification. In Proceedings of the 1st Conference on Fairness, Accountability and Transparency, 77–91. PMLR, 2018. URL: http://proceedings.mlr.press/v81/buolamwini18a.html.

[Das18]

Jeffrey Dastin. Amazon scraps secret ai recruiting tool that showed bias against women. Reuters, octubre 2018. URL: https://www.reuters.com/article/us-amazon-com-jobs-automation-insight-idUSKCN1MK08G.

[HdHPK14]

Christopher Holdgraf, Wendy de Heer, Brian Pasley, and Robert Knight. Evidence for predictive coding in human auditory cortex. In International Conference on Auditory Cortex. Brisbane, Australia, 2014.

[MH13]

Zeev Maoz and Errol A. Henderson. The world religion dataset, 1945-2010: logic, estimates, and trends. International Interactions, 39(3):265–291, 2013. URL: https://correlatesofwar.org/data-sets/world-religion-data/, doi:10.1080/03050629.2013.782306.

[McK22]

Wes McKinney. Python for Data Analysis: Data Wrangling with pandas, NumPy, and Jupyter. O'Reilly Media, Sebastopol, CA, 3rd edition, 2022. ISBN 978-1098104030.

[ONeil16]

Cathy O'Neil. Weapons of Math Destruction: How Big Data Increases Inequality and Threatens Democracy. Crown, New York, 2016. ISBN 978-0553418811.

[Rea81]

Ronald Reagan. Inaugural address. Discurso de inauguración presidencial, enero 1981. Primer discurso inaugural de Ronald Reagan como presidente de Estados Unidos. URL: https://www.reaganlibrary.gov/archives/speech/inaugural-address-1981.

[Sus19]

Anjana Susarla. The emergence of deepfake technology: a review. Technology Innovation Management Review, 9(11):39–52, 2019. URL: https://timreview.ca/article/1282.

[Toe22]

Rob Toews. Deepfakes are going to wreak havoc on society. we are not prepared. Forbes, mayo 2022. URL: https://www.forbes.com/sites/robtoews/2020/05/25/deepfakes-are-going-to-wreak-havoc-on-society-we-are-not-prepared/.

[Comparitech25]

Comparitech. Password statistics: the most common passwords. 2025. Estadísticas sobre contraseñas más comunes. URL: https://www.comparitech.com/blog/information-security/password-statistics/.

[CongresoNdChile99]

Congreso Nacional de Chile. Ley n° 19.628 sobre protección de la vida privada. 1999. Ley chilena sobre protección de datos personales. URL: https://www.bcn.cl/leychile/navegar?idNorma=141599.

[CongresoNdChile24]

Congreso Nacional de Chile. Proyecto de ley sobre inteligencia artificial. 2024. Boletín N° 15.153-19. URL: https://www.camara.cl/legislacion/ProyectosDeLey/tramitacion.aspx?prmID=15344.

[Educarchile24]

Educarchile. Privacidad y seguridad digital para estudiantes. 2024. Recursos educativos sobre ciudadanía digital. URL: https://www.educarchile.cl/.

[EuropeanPaCotEUnion18]

European Parliament and Council of the European Union. General data protection regulation (gdpr). Regulation (EU) 2016/679, 2018. Reglamento General de Protección de Datos de la Unión Europea. URL: https://eur-lex.europa.eu/eli/reg/2016/679/oj.

[EuropeanPaCotEUnion24]

European Parliament and Council of the European Union. Artificial intelligence act. Regulation (EU) 2024/1689, 2024. Reglamento de la Unión Europea sobre Inteligencia Artificial. URL: https://eur-lex.europa.eu/eli/reg/2024/1689/oj.

[Experian24]

Experian. What is the dark web and how to access it safely. 2024. Información sobre la dark web y seguridad. URL: https://www.experian.com/blogs/ask-experian/what-is-the-dark-web/.

[FacebookAI24]

Facebook AI. Deepfake detection challenge. 2024. Iniciativa para detectar deepfakes. URL: https://ai.facebook.com/datasets/dfdc/.

[LISAInstitute24]

LISA Institute. Deepfakes: guía completa sobre qué son y cómo detectarlos. 2024. Recurso educativo sobre deepfakes. URL: https://www.lisainstitute.com/blogs/blog/deepfakes-guia-completa.

[MinisteriodCienciaTecnologiaCeInnovacion24]

Ministerio de Ciencia, Tecnología, Conocimiento e Innovación. Política nacional de inteligencia artificial. 2024. Estrategia de Chile para el desarrollo de la IA. URL: https://www.minciencia.gob.cl/politicaIA.

[NorthpointeInc17]

Northpointe Inc. Compas risk scales: demonstrating accuracy equity and predictive parity. Technical Report, Northpointe, 2017. URL: https://www.equivant.com/response-to-propublica-demonstrating-accuracy-equity-and-predictive-parity/.

[pandasdteam24]

pandas development team. Pandas documentation. 2024. Biblioteca de Python para análisis de datos. URL: https://pandas.pydata.org/docs/.

[PyPDF2Contributors24]

PyPDF2 Contributors. Pypdf2 documentation. 2024. Biblioteca Python para manipulación de archivos PDF. URL: https://pypdf2.readthedocs.io/.

Learn more

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