How to display frontmatter in html pages with sphinx

[fervand1]

Hello I was trying to add frontmatter in .md files which could be displayed also on the static web page built with sphinx "myst_parser" but it doesn't seem to display it. Is it possible to render html for front matter?

Following is the example I tried in my .md file. The rest of the body content is displayed fine but this gets skipped.

Update: I have also read about deflists for sphinx, https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html
But I am still wondering if there could be a way to show frontmatter in final output

---
title: My First Article
thumbnail: ./thumbnails/nice-image.png
date: 2022-05-11
authors:
  - name: Test
    affiliations:
      - University of Europe
---

[72757373656c6c]

I believe the answer is a qualified "yes, there is a way". Documented:

• https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#substitutions-with-jinja2

The syntax changed (0.18.0 - 2022-06-07):

• https://myst-parser.readthedocs.io/en/latest/develop/_changelog.html#breaking-changes

The old syntax will still work, you'll get a warning, "1: WARNING: top-level 'substitutions' key is deprecated, place under 'myst' key instead [myst.topmatter]".

The snippet from the changelog is shown below.

---

---
html_meta:
  "description lang=en": "metadata description"
substitutions:
  key1: I'm a **substitution**
---

is replaced by:

---
myst:
  html_meta:
    "description lang=en": "metadata description"
  substitutions:
    key1: I'm a **substitution**
---

Reference theses using the following syntax: {{ key1 }}.

The way I found this information was to search https://myst-parser.readthedocs.io/en/latest for "front matter". Make sure you are on the latest otherwise your search won't find the current and correct documentation.

Your OP mentions a specific sphinx documentation URL. That's a good question, I am not sure about the Sphinx-specific page front matter. The documentation mentioned the Jinja2 syntax:

    - version: {{ env.config.version }}
    - docname: {{ env.docname | upper }}
    - {{ "a" + "b" }}

Perhaps someone will chime in with more details.

[holmboe]

Also see #947 for accessing frontmatter in the env.metadata dict top level instead of mapping the substitutions dict to keys.