|
| 1 | +# Markdown Files |
| 2 | + |
| 3 | +Whether you write your book's content in Jupyter Notebooks (`.ipynb`) or |
| 4 | +in regular markdown files (`.md`), you'll write in the same flavor of markdown |
| 5 | +called **MyST Markdown**. |
| 6 | + |
| 7 | +## What is MyST? |
| 8 | + |
| 9 | +MyST stands for "Markedly Structured Text". It |
| 10 | +is a slight variation on a flavor of markdown called "CommonMark" markdown, |
| 11 | +with small syntax extensions to allow you to write **roles** and **directives** |
| 12 | +in the Sphinx ecosystem. |
| 13 | + |
| 14 | +## What are roles and directives? |
| 15 | + |
| 16 | +Roles and directives are two of the most powerful tools in Jupyter Book. They |
| 17 | +are kind of like functions, but written in a markup language. They both |
| 18 | +serve a similar purpose, but **roles are written in one line**, whereas |
| 19 | +**directives span many lines**. They both accept different kinds of inputs, |
| 20 | +and what they do with those inputs depends on the specific role or directive |
| 21 | +that is being called. |
| 22 | + |
| 23 | +### Using a directive |
| 24 | + |
| 25 | +At its simplest, you can insert a directive into your book's content like so: |
| 26 | + |
| 27 | +```` |
| 28 | +```{mydirectivename} |
| 29 | +My directive content |
| 30 | +``` |
| 31 | +```` |
| 32 | + |
| 33 | +This will only work if a directive with name `mydirectivename` already exists |
| 34 | +(which it doesn't). There are many pre-defined directives associated with |
| 35 | +Jupyter Book. For example, to insert a note box into your content, you can |
| 36 | +use the following directive: |
| 37 | + |
| 38 | +```` |
| 39 | +```{note} |
| 40 | +Here is a note |
| 41 | +``` |
| 42 | +```` |
| 43 | + |
| 44 | +This results in: |
| 45 | + |
| 46 | +```{note} |
| 47 | +Here is a note |
| 48 | +``` |
| 49 | + |
| 50 | +In your built book. |
| 51 | + |
| 52 | +For more information on writing directives, see the |
| 53 | +[MyST documentation](https://myst-parser.readthedocs.io/). |
| 54 | + |
| 55 | + |
| 56 | +### Using a role |
| 57 | + |
| 58 | +Roles are very similar to directives, but they are less-complex and written |
| 59 | +entirely on one line. You can insert a role into your book's content with |
| 60 | +this pattern: |
| 61 | + |
| 62 | +``` |
| 63 | +Some content {rolename}`and here is my role's content!` |
| 64 | +``` |
| 65 | + |
| 66 | +Again, roles will only work if `rolename` is a valid role's name. For example, |
| 67 | +the `doc` role can be used to refer to another page in your book. You can |
| 68 | +refer directly to another page by its relative path. For example, the |
| 69 | +role syntax `` {doc}`intro` `` will result in: {doc}`intro`. |
| 70 | + |
| 71 | +For more information on writing roles, see the |
| 72 | +[MyST documentation](https://myst-parser.readthedocs.io/). |
| 73 | + |
| 74 | + |
| 75 | +### Adding a citation |
| 76 | + |
| 77 | +You can also cite references that are stored in a `bibtex` file. For example, |
| 78 | +the following syntax: `` {cite}`holdgraf_evidence_2014` `` will render like |
| 79 | +this: {cite}`holdgraf_evidence_2014`. |
| 80 | + |
| 81 | +Moreover, you can insert a bibliography into your page with this syntax. |
| 82 | +The `{bibliography}` directive must be used for all the `{cite}` roles to |
| 83 | +render properly. |
| 84 | +For example, if the references for your book are stored in `references.bib`, |
| 85 | +then the bibliography is inserted with: |
| 86 | + |
| 87 | +```` |
| 88 | +```{bibliography} references.bib |
| 89 | +``` |
| 90 | +```` |
| 91 | + |
| 92 | +Resulting in a rendered bibliography that looks like: |
| 93 | + |
| 94 | +```{bibliography} references.bib |
| 95 | +``` |
| 96 | + |
| 97 | + |
| 98 | +### Executing code in your markdown files |
| 99 | + |
| 100 | +If you'd like to include computational content inside these markdown files, |
| 101 | +you can use MyST Markdown to define cells that will be executed when your |
| 102 | +book is built. Jupyter Book uses *jupytext* to do this. |
| 103 | + |
| 104 | +First, add Jupytext metadata to the file. For example, to add Jupytext metadata |
| 105 | +to this markdown page, run this command: |
| 106 | + |
| 107 | +``` |
| 108 | +jupyter-book myst init markdown.md |
| 109 | +``` |
| 110 | + |
| 111 | +Once a markdown file has Jupytext metadata in it, you can add the following |
| 112 | +directive to run the code at build time: |
| 113 | + |
| 114 | +```` |
| 115 | +```{code-cell} |
| 116 | +print("Here is some code to execute") |
| 117 | +``` |
| 118 | +```` |
| 119 | + |
| 120 | +When your book is built, the contents of any `{code-cell}` blocks will be |
| 121 | +executed with your default Jupyter kernel, and their outputs will be displayed |
| 122 | +in-line with the rest of your content. |
| 123 | + |
| 124 | +For more information about executing computational content with Jupyter Book, |
| 125 | +see [The MyST-NB documentation](https://myst-nb.readthedocs.io/). |
0 commit comments