support prolog (& epilog) content

[chrisjsewell]

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 https://github.com/executablebooks/MyST-Parser/issues/188#issuecomment-661875933

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)

[chrisjsewell]

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

[chrisjsewell]

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 }}

[choldgraf]

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

[renefritze]

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?

[mforbes]

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.

[chrisjsewell]

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

[mforbes]

@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.

[chrisjsewell]

cheers!

[dbitouze]

[...]

then in each file you would add at the top

{{ prolog }}

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