support prolog (& epilog) content

@SG-phimeca

Is there a way to pur the role definition in the conf.py configuration file ? Idealy this should not be in content source file.

Originally posted by @SG-phimeca in #188 (comment)

This would be similar to https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_prolog. An important difference though would be that the content should be injected after any YAML front matter (perhaps there could also be a separate option to add to this front matter)

It would also be idea to offer it as a template like construct, similar to https://nbsphinx.readthedocs.io/en/0.3.0/prolog-and-epilog.html, such that one could adjust the behaviour based on variables like the docname

Although not specifically addressed, #273 provides a close solution to this, for example:

in conf.py

myst_substitutions = {
   "prolog": """
    <meta property="og:site_name" content="Homepage and blog of Hynek Schlawack">
    <meta property="og:author" content="Hynek Schlawack">
    <meta property="og:type" content="article">
    <meta property="og:title" content="Waiting in asyncio">
    <meta property="og:description" content="One of the main appeals of using Python’s asyncio is being able to fire off many coroutines and run them concurrently. How many ways do you know for waiting for their results?">
    <meta property="og:url" content="https://hynek.me/articles/waiting-in-asyncio/">
    <meta property="article:published_time" content="2020-05-21T00:00:00Z">
    <meta name=twitter:card content="summary">
    <meta name=twitter:site content="@hynek">
    <meta name=twitter:creator content="@hynek">
    <meta name=twitter:image content="https://hynek.me/img/avatar.jpg">
    <meta name=twitter:title content="Waiting in asyncio">
    <meta name=twitter:description content="One of the main appeals of using Python’s asyncio is being able to fire off many coroutines and run them concurrently. How many ways do you know for waiting for their results?">
"""
}

then in each file you would add at the top

{{ prolog }}

wait where is this myst_substitutions dark magic documented? I just did a search for myst_substitutions in the parser docs and didn't find it, that is cool! Is there a way to do this within-page in order to have a MyST version of rST substitutions?

EDIT: nvm I read this issue before seeing the others about substitution syntax being added, will comment there

Although not specifically addressed, #273 provides a close solution to this, for example:

in conf.py
myst_substitutions = {
   "prolog": """
SNIP
"""
}
then in each file you would add at the top
{{ prolog }}

I've tried this with a substitution that contains a code-cell directive. Am I doing something wrong if that results in this kind of warnings?

WARNING: Found an unexpected `code-cell` directive. Either this file was not converted to a notebook, because Jupytext header content was missing, or the `code-cell` was not converted, because it is nested. See https://myst-nb.readthedocs.io/en/latest/use/markdown.html for more information.

If using a code-cell simply isn't supported atm, is there a workaround?

This might not be the correct place to ask, but can substitutions like {{ prolog }} be used in template files (like _templates/layout.html)? It seems like Jinja is run on these before myst_substitutions is parsed or used. Please let me know if I am missing something, or if I should open a new issue. Thanks.

but can substitutions like {{ prolog }} be used in template files (like _templates/layout.html)?

Heya, no not directly, since they have completely different "contexts", i.e. the dictionary that maps the variables to their values.
The one for the templates can be added to via https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_context

So maybe you could try something like this in your conf.py

myst_substitutions = {"a": "b"}
html_context = {"myst": myst_substitutions}

then use {{ myst.prolog }} in the template file

@chrisjsewell

@chrisjsewell Thanks! This makes sense and is probably the right thing - I realize I was abusing myst_substitutions (I had HTML specific things that make more sense in html_context). I will make a PR with a doc update when I get a chance.

cheers!

[...]

then in each file you would add at the top
{{ prolog }}

Not ideal when you have about thousand files in your documentation...

BUG: Explicitly include MathJaX in layout.html

Any progress on this? I found copy-and-paste {{ prolog }} is somehow fragile after I forgot to paste it into some files.

Navigation Menu

Repository navigation

support prolog (& epilog) content #190

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

support prolog (& epilog) content #190

Description

Activity

chrisjsewell commented on Jul 22, 2020

chrisjsewell commented on Dec 17, 2020

choldgraf commented on Dec 17, 2020

renefritze commented on Jan 26, 2021

mforbes commented on Sep 22, 2021

chrisjsewell commented on Sep 22, 2021

mforbes commented on Sep 22, 2021

chrisjsewell commented on Sep 22, 2021

dbitouze commented on Dec 6, 2022

StageDog commented on Aug 26, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions