Document executable markdown files

[rowanc1]

We likely need something like this in the frontmatter.

---
jupytext:
  formats: md:myst
  text_representation:
    extension: .md
    format_name: myst
kernelspec:
  display_name: Python 3
  language: python
  name: python3
---

Previous docs page is here: https://jupyterbook.org/en/stable/file-types/myst-notebooks.html

Portions are here: https://mystmd.org/guide/notebooks-with-markdown

Suggested actions

Define two pages under the Executable Content section. These are the two titles/topics:

1. Notebooks written in markdown. How to define markdown files in a way that they will be treated as notebooks and executed (e.g. front-matter etc). Mention code-cell but don't go into much detail.
2. Cell and in-line execution with Markdown. How to define block- and inline-level execution with Markdown.

[agoose77]

@rowanc1 this is already covered here: https://mystmd.org/guide/notebooks-with-markdown#kernel-specification

Do you think it's not discoverable enough?

Ah, just seen some discussion on Discord.

[agoose77]

@rowanc1 @choldgraf I actually think our existing content is somewhat well partitioned between the different docs pages, but their titles / organisation is not clear.

I took a moment to re-name things a little:

I think this is a lot clearer already. At a discursive level, we have:

1. Executable Markdown Files ({code-cell} and {eval})
2. Execute During Build (ipynb or .md files can be executed with --execute)
3. Embed & Reuse Outputs (outputs can be used in other contexts)
4. Generate Rich Outputs (I don't love this title, focus on making the most of richness, and controlling its appearance for site builds)
5. Adding read-time execution to websites

These files are all distinct with clear distinct purposes. I wonder if there is a way to better separate the three core concepts here:

• "Static" execution during build
• "Interactive" execution at read-time
• Dynamic / rich views at read-time

But this would already be an improvement.

[choldgraf]

This definitely feels like an improvement in clarity to me!