Guidance/standardization of "front matter"

[OriolAbril]

I remember at some point discussing the possibility to in addition to the tags and categories that will already give an idea of the notebook topics and difficulty, we could define some kind of standard front matter so that all notebook have a quick explanation about what knowledge is assumed, links to notebooks that explain those concepts that are treated as known by the reader..

[Sayam753]

Cross posting from slack -
We need to also standardise on how to handle external dependencies for notebooks. A simple idea is to do a pip/conda install at the start of notebooks.

edit: useful reference: https://twitter.com/aureliengeron/status/1445950207754006530?s=20

[OriolAbril]

"frontmatter" proposal:

(notebook_id)=
# Notebook title

|badges| |binder| |colab| (hopefully automated)

:::{post} date
:tags: tag1, tag2
:category: level
:::

:::{dropdown} Notebook dependencies
:icon: package-dependencies

In order to run this notebook you'll need to install pymc3 + link to install guide.

For this notebook you'll also need to install bambi+link to bambi.

This could also go in a separate hidden cell (so it's not visible in website but it's visible in notebook)
:::

:::{dropdown} Suggested reading
:icon: book 

This notebook assumes you are familiar with x, y and z. If you are not, consider reading notebook on x, notebook on y... before reading this notebook.

[OriolAbril]

We could also use substitutions to keep the extra content in the notebooks to a minimum: https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#substitutions-with-jinja2

[OriolAbril]

idea (needs to be tested): provide some templates for installation instructions, could have a paragraph of intro, be inside a dropdown, have tabs within the dropdown for pip/conda installs... but leave the packages to be installed as jinja substitutions. We can then add notebook metadata to define the substitutions, see https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#substitutions-with-jinja2.

main expected problem: install commands should probably be formatted as code but I don't know how to get jinja to work inside code.

[drbenvincent]

Is this issue now defunct/solved given we have the Style Guide?