Code Cells and Inline Expressions with Markdown

You can specify Jupyter content in your markdown, which allows you to execute computation using MyST’s notebook execution engine.

You can define two types of markdown-based computation:

• code cells: for block-level content
• in-line expressions: for content inline with surrounding text

Code cells with the {code-cell} directive¶

You can use the {code-cell} directive to create block-level computational outputs in MyST Markdown.

{code-cell} directives have the following form:

```{code-cell} LANGUAGE
:key: value

CODE TO BE EXECUTED
```

• LANGUAGE defines the language to be used in executing the code.
• :key: value pairs will be treated as cell-level metadata.
• CODE TO BE EXECUTED will be executed by the LANGUAGE kernel at build time.

For example, the following directive inserts a code cell into the page, and will be executed if you specify --execute with your MyST build.

```{code-cell} python
hello = "hello"
there = "there"
phrase = f"{hello}, {there}!"
print(phrase)
```

Add tags to {code-cell} directives¶

You can add tags to the {code-cell} directive. They will be parsed and used in the same way that cell tag metadata is used in .ipynb files.

For example, the following code defines a remove-input tag:

```{code-cell} python
:tags: remove-input
print("This will show output with no input!")
```

and results in the following:

print("This will show output with no input!")

This will show output with no input!

This can be particularly helpful for showing the output of a calculation or plot, which is reproducible in the source code, but not shown to the user like this matplotlib plot:

For multiple tags you have two ways to provide them:

• If you specify argument options with :, tags will be parsed as a comma-separated string. For example:

  ```{code-cell} python
  :tags: tag1, tag2,tag3
  # Note that whitespace is removed from tags!
  print("howdy!")
  ```

• If you specify argument options with YAML, tags should be given as a YAML list. For example:

  ```{code-cell} python
  ---
  tags:
  - tag1
  - tag2
  ---
  print("howdy!")
  ```

For more about how to specify directive options, see MyST Syntax Overview.

Inline expressions with the {eval} role¶

You can use the {eval} role to evaluate code that is surrounded by text. This allows you to quickly insert its output in a way that flows with the text around it.

For example, the following MyST Markdown would re-use the variable defined above.

The phrase is: {eval}`phrase`.

This results in the following:

The phrase is: 'hello, there!'.

You can also modify the expression at the time of computation, for example:

The phrase manually computed is: {eval}`f"{hello}, {there} everybody!"`

This results in the following:

The phrase manually computed is: 'hello, there everybody!'