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.

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.

What are 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.

Using a directive

At its simplest, you can insert a directive into your book’s content like so:

```{mydirectivename}
My directive content
```

This will only work if a directive with name mydirectivename already exists (which it doesn’t). There are many pre-defined directives associated with Jupyter Book. For example, to insert a note box into your content, you can use the following directive:

```{note}
Here is a note
```

This results in:

Note

Here is a note

In your built book.

For more information on writing directives, see the MyST documentation.

Using a role

Roles are very similar to directives, but they are less-complex and written entirely on one line. You can insert a role into your book’s content with this pattern:

Some content {rolename}`and here is my role's content!`

Again, roles will only work if rolename is a valid role’s name. For example, the doc role can be used to refer to another page in your book. You can refer directly to another page by its relative path. For example, the role syntax {doc}`intro` will result in: Machine Learning in Python.

For more information on writing roles, see the MyST documentation.

Adding a citation

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:

```{bibliography}
```

Resulting in a rendered bibliography that looks like:

[AP11]

Hussein A Abdou and John Pointon. Credit scoring, statistical techniques and evaluation criteria: a review of the literature. Intelligent systems in accounting, finance and management, 18(2-3):59–88, 2011.

[ALCS18]

Rishav Raj Agarwal, Chia-Ching Lin, Kuan-Ta Chen, and Vivek Kumar Singh. Predicting financial trouble using call data—on social capital, phone logs, and financial trouble. PloS one, 13(2):e0191863, 2018.

[ArraizBS17]

Irani Arráiz, Miriam Bruhn, and Rodolfo Stucchi. Psychometrics as a tool to improve credit information. The World Bank Economic Review, 30(Supplement_1):S67–S76, 2017.

[Bre96]

L. Breiman. Bagging predictors. Machine Learning, 1996.

[Bre01]

L. Breiman. Random forests. Machine Learning, 2001.

[CL09]

Chun-Ling Chuang and Rong-Ho Lin. Constructing a reassigning credit scoring model. Expert Systems with Applications, 36(2):1685–1694, 2009.

[CV95]

C. Cortes and V. Vapnik. Support-vector networks. Machine Learning, 1995.

[CH67]

T. M. Cover and P. E. Hart. Nearest neighbor pattern classification. IEEE Transactions on Information Theory, 1967.

[Cox58]

D. R. Cox. The regression analysis of binary sequences. Journal of the Royal Statistical Society, 1958.

[DCMS+19]

Sofie De Cnudde, Julie Moeyersoms, Marija Stankova, Ellen Tobback, Vinayak Javaly, and David Martens. What does your facebook profile reveal about your creditworthiness? using alternative data for microfinance. Journal of the Operational Research Society, 70(3):353–363, 2019.

[dOKCC+11]

Rodrigo de Oliveira, Alexandros Karatzoglou, Pedro Concejero Cerezo, Ana Armenta Lopez de Vicuña, and Nuria Oliver. Towards a psychographic user model from mobile phone usage. In CHI'11 Extended Abstracts on Human Factors in Computing Systems, pages 2191–2196. 2011.

[DCCH21]

Viani B Djeundje, Jonathan Crook, Raffaella Calabrese, and Mona Hamid. Enhancing credit scoring with alternative data. Expert Systems with Applications, 163:113766, 2021.

[DH73]

R. O. Duda and P. E. Hart. Pattern classification and scene analysis. Wiley, 1973.

[Fis36]

R. A. Fisher. The use of multiple measurements in taxonomic problems. Annals of Eugenics, 1936.

[FS97]

Y. Freund and R. E. Schapire. A decision-theoretic generalization of on-line learning and an application to boosting. Journal of Computer and System Sciences, 1997.

[Fri01]

J. H. Friedman. Greedy function approximation: a gradient boosting machine. The Annals of Statistics, 2001.

[GFGZ17]

Ruyi Ge, Juan Feng, Bin Gu, and Pengzhu Zhang. Predicting and deterring default with social media information in peer-to-peer lending. Journal of Management Information Systems, 34(2):401–424, 2017.

[GPAM+14]

I. Goodfellow, J. Pouget-Abadie, M. Mirza, B. Xu, D. Warde-Farley, S. Ozair, A. Courville, and Y. Bengio. Generative adversarial networks. arXiv preprint, 2014.

[GVBB+21]

Björn Rafn Gunnarsson, Seppe Vanden Broucke, Bart Baesens, María Óskarsdóttir, and Wilfried Lemahieu. Deep learning for credit scoring: do or don’t? European Journal of Operational Research, 295(1):292–305, 2021.

[HDWD23]

Ola Hall, Francis Dompae, Ibrahim Wahab, and Fred Mawunyo Dzanku. A review of machine learning and satellite imagery for poverty prediction: implications for development research and applications. Journal of International Development, 35(7):1753–1768, 2023. URL: https://onlinelibrary.wiley.com/doi/abs/10.1002/jid.3751, arXiv:https://onlinelibrary.wiley.com/doi/pdf/10.1002/jid.3751, doi:https://doi.org/10.1002/jid.3751.

[HRM24]

Rivalani Hlongwane, Kutlwano KKM Ramaboa, and Wilson Mongwe. Enhancing credit scoring accuracy with a comprehensive evaluation of alternative data. Plos one, 19(5):e0303566, 2024.

[HK70]

A. E. Hoerl and R. W. Kennard. Ridge regression: biased estimation for nonorthogonal problems. Technometrics, 1970.

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

[LBBH98]

Y. LeCun, L. Bottou, Y. Bengio, and P. Haffner. Gradient-based learning applied to document recognition. Proceedings of the IEEE, 1998.

[LBST15]

Stefan Lessmann, Bart Baesens, Hsin-Vonn Seow, and Lyn C Thomas. Benchmarking state-of-the-art classification algorithms for credit scoring: an update of research. European Journal of Operational Research, 247(1):124–136, 2015.

[MP00]

G. McLachlan and D. Peel. Finite mixture models. Wiley, 2000.

[NalicMartinovicvZagar20]

Jasmina Nalić, Goran Martinović, and Drago Žagar. New hybrid data mining model for credit scoring based on feature selection algorithm and ensemble classifiers. Advanced Engineering Informatics, 45:101130, 2020.

[OLT20]

Henri Ots, Innar Liiv, and Diana Tur. Mobile phone usage data for credit scoring. In Databases and Information Systems: 14th International Baltic Conference, DB&IS 2020, Tallinn, Estonia, June 16–19, 2020, Proceedings 14, 82–95. Springer, 2020.

[PPO15]

Jose San Pedro, Davide Proserpio, and Nuria Oliver. Mobiscore: towards universal credit scoring from mobile phone data. In International conference on user modeling, adaptation, and personalization, 195–207. Springer, 2015.

[Rab89]

L. R. Rabiner. A tutorial on hidden markov models and selected applications in speech recognition. Proceedings of the IEEE, 1989.

[Ros58]

F. Rosenblatt. The perceptron: a probabilistic model for information storage and organization in the brain. Psychological Review, 1958.

[RS23]

Pranith K Roy and Krishnendu Shaw. A credit scoring model for smes using ahp and topsis. International Journal of Finance & Economics, 28(1):372–391, 2023.

[RHW86]

D. E. Rumelhart, G. E. Hinton, and R. J. Williams. Learning representations by back-propagating errors. Nature, 1986.

[Tib96]

R. Tibshirani. Regression shrinkage and selection via the lasso. Journal of the Royal Statistical Society, 1996.

[TEC18]

Diwakar Tripathi, Damodar Reddy Edla, and Ramalingaswamy Cheruku. Hybrid credit scoring model using neighborhood rough set and multi-layer ensemble classification. Journal of Intelligent & Fuzzy Systems, 34(3):1543–1549, 2018.

[Tri20]

Shrawan Kumar Trivedi. A study on credit scoring modeling with different feature selection and machine learning approaches. Technology in Society, 63:101413, 2020.

[WYVdBD16]

Yanhao Wei, Pinar Yildirim, Christophe Van den Bulte, and Chrysanthos Dellarocas. Credit scoring with social network data. Marketing Science, 35(2):234–258, 2016.

[Wes00]

David West. Neural network credit scoring models. Computers & operations research, 27(11-12):1131–1152, 2000.

[YOH11]

Bee Wah Yap, Seng Huat Ong, and Nor Huselina Mohamed Husain. Using data mining to improve assessment of credit worthiness via credit scoring models. Expert Systems with Applications, 38(10):13274–13283, 2011.

[ZHXW21]

Xinwei Zhang, Yaoci Han, Wei Xu, and Qili Wang. Hoba: a novel feature engineering methodology for credit card fraud detection with a deep learning architecture. Information Sciences, 557:302–316, 2021.

[OskarsdottirBS+19]

María Óskarsdóttir, Cristián Bravo, Carlos Sarraute, Jan Vanthienen, and Bart Baesens. The value of big data for credit scoring: enhancing financial inclusion using mobile phone data and social network analytics. Applied Soft Computing, 74:26–39, 2019.

Executing code in your markdown files

If you’d like to include computational content inside these markdown files, you can use MyST Markdown to define cells that will be executed when your book is built. Jupyter Book uses jupytext to do this.

First, add Jupytext metadata to the file. For example, to add Jupytext metadata to this markdown page, run this command:

jupyter-book myst init markdown.md

Once a markdown file has Jupytext metadata in it, you can add the following directive to run the code at build time:

```{code-cell}
print("Here is some code to execute")
```

When your book is built, the contents of any {code-cell} blocks will be executed with your default Jupyter kernel, and their outputs will be displayed in-line with the rest of your content.

For more information about executing computational content with Jupyter Book, see The MyST-NB documentation.