Project settings - MyST Markdown

The settings field in the project or page frontmatter allows you to change how the parsing, transforms, plugins, or other behaviors of mystmd.

Here’s an example of settings specified in project frontmatter

myst.yml

project:
  settings:
    output_matplotlib_strings: remove
    output_stderr: remove-warn

Here’s an example of settings in page frontmatter

page.md

settings:
  output_matplotlib_strings: remove
  output_stderr: remove-warn

Available settings fields¶

output_stderr

Remove, warn or error on stderr outputs. (e.g. DeprecationWarnings, RuntimeWarnings)

"show": (default): show all stderr (unless a remove-stderr tag is present on the cell)
"remove": remove all stderr outputs
"remove-warn" or "remove-error": remove all stderr, and log a warning or error
"warn" or “error”: log a warning or error if a stderr is found

Can be controlled or overridden by a notebook cell tag.

output_stdout

Remove, warn or error on stdout outputs. (e.g. long text outputs, like text-based progress bars)

"show": (default): show all stdout (unless a remove-stdout tag is present on the cell)
"remove": remove all stdout outputs
"remove-warn" or "remove-error": remove all stdout, and log a warning or error
"warn" or “error”: log a warning or error if a stdout is found

Can be controlled or overridden by a notebook cell tag.

output_matplotlib_strings

Remove, warn, or error on cell outputs that return a string-based Python object (e.g., matplotlib strings outputs, such as <Figure size 720x576 with 1 Axes> or Text(0.5, 0.98, 'Test 1')). These can also be suppressed by ending your cell content with a semicolon in Jupyter Notebooks. The default is to remove these and warn ("remove-warn").

"show": show all matplotlib strings in outputs
"remove": remove all matplotlib strings in outputs
"remove-warn" (default) or "remove-error": remove all matplotlib strings in outputs, and log a warning or error
"warn" or “error”: log a warning or error if matplotlib strings in outputs

LaTeX Rendering Settings¶

Adding an object of myst_to_tex to the settings will allow you to control various default parts of how the LaTeX renderer behaves.

code_style

Change the code rendering when writing code.

"verbatim" (default): Use the \begin{verbatim} environment
"minted": Use the \begin{minted} environment with the language of the code block used
"listings": Use the \begin{listings} environment with the language of the code block used

beamer

Indicate you are building a beamer presentation.

true: Add \begin{frame} environment for each block, delimited by +++, and enable presentation outline with block metadata +++ {"outline":true}
false (default): No extra \begin{frame} environment will be used

Error Rules¶

The error_rules list in the project configuration can be used to disable or modify logging rules in the CLI:

myst.yml

project:
  error_rules:
    - rule: math-eqnarray-replaced
      severity: ignore
    - rule: link-resolves
      severity: ignore
      keys:
        - /known-internal-link
        - https://flaky-connection.com
        - 'https://example.org/**'
        - 'https://*.example.com/**'

The severity of each rule can be set to ignore, warn, or error. If the rule is triggered, then the severity listed will be adopted rather than the default log message severity. The default severity for rules included in the list is ignore, which means that simply listing the rule IDs as strings will ignore those rules. To discover the rule ID, run myst in debug mode (i.e. myst --debug build) to get the error (and optional key) printed to the console. For example, the above configuration updates will no longer warn on math-eqnarray-replaced and will also ignore the two links when running myst build --check-links --strict in continuous integration.

Some error rules support a key field that identifies specific instances of the error. This allows you to target particular cases rather than all instances of a rule. For example, the link-resolves rule uses the URL as the key, allowing you to ignore specific broken links while still checking others. Similarly, the doi-link-valid rule uses the DOI value as the key, so you can ignore specific invalid DOIs while still validating others. When a rule supports keys, you can provide a list of keys (or key patterns) in the keys field to match multiple specific instances.

List of Error Rules

The full list of errors and warnings used across MyST with their defaults shown.

valid-config-structure [error]: Configuration file structure is valid and can be parsed
site-config-exists [error]: Site configuration is found in project
project-config-exists [warn]: Project configuration file exists in the directory
valid-site-config [error]: Site configuration passes validation
valid-project-config [error]: Project configuration passes validation
config-has-no-deprecated-fields [error]: Configuration uses current field names without deprecated options
frontmatter-is-yaml [error]: Frontmatter can be parsed as valid YAML
valid-page-frontmatter [error]: Page frontmatter passes validation
valid-frontmatter-export-list [error]: Export list in frontmatter is valid for the specified format
docx-renders [error]: DOCX document renders without errors
jats-renders [error]: JATS XML renders without errors
md-renders [error]: Markdown output renders without errors
meca-includes-jats [warn]: MECA bundle contains required JATS file
meca-exports-built [warn]: MECA archive builds without errors
meca-files-copied [error]: MECA files copy to output successfully
pdf-build-commands-available [error]: Required PDF build tools (LaTeX/Typst) are installed
pdf-builds-without-errors [error]: PDF compilation completes without LaTeX/Typst errors
pdf-builds [error]: PDF file generates successfully
tex-renders [error]: LaTeX/Typst document renders without errors
export-extension-correct [error]: Export file has the correct extension for its format
export-article-exists [error]: Article file specified in export configuration exists
tex-parses [error]: LaTeX content parses without syntax errors
jats-parses [error]: JATS XML parses without syntax errors
myst-file-loads [error]: MyST markdown file loads and parses successfully
selected-file-is-processed [error]: File specified for processing is found and processed
directive-registered [warn]: Directive is registered without name conflicts
directive-known [error]: Directive name is recognized
directive-argument-correct [error]: Directive argument matches specification
directive-options-correct [error]: Directive options are valid and properly formatted
directive-body-correct [error]: Directive body content meets requirements
role-registered [warn]: Role is registered without name conflicts
role-known [error]: Role name is recognized
role-body-correct [error]: Role content meets requirements
toc-contents-exist [error]: Files referenced in table of contents exist
encountered-legacy-toc [warn]: Table of contents uses deprecated format
valid-toc-structure [error]: Table of contents structure passes schema validation
valid-toc [warn]: Table of contents is valid
image-downloads [error]: Remote image downloads successfully
image-exists [error]: Image file exists at specified path
image-format-converts [error]: Image format converts successfully using available tools
image-copied [error]: Image copies to output directory successfully
image-format-optimizes [warn]: Image format optimizes successfully
math-label-lifted [warn]: Math equation label extracts successfully
math-equation-env-removed [warn]: Nested equation environment removes successfully
math-eqnarray-replaced [warn]: Deprecated eqnarray environment replaces with align
math-alignment-adjusted [warn]: Math alignment adjusts successfully
math-renders [error]: Math expression renders with KaTeX without errors
reference-template-fills [warn]: Reference template populates with values successfully
identifier-is-unique [warn]: Identifier is unique across the project
reference-target-resolves [warn]: Cross-reference target is found
reference-syntax-valid [warn]: Reference syntax is valid
reference-target-explicit [warn]: Reference target is explicitly specified
footnote-references-definition [warn]: Footnote reference links to an existing definition
intersphinx-references-resolve [error]: Intersphinx cross-reference resolves to external documentation
myst-link-valid [error]: MyST-formatted link is valid
sphinx-link-valid [error]: Sphinx-style link is valid
rrid-link-valid [warn]: RRID (Research Resource Identifier) link is valid
ror-link-valid [error]: ROR (Research Organization Registry) link is valid
wikipedia-link-valid [error]: Wikipedia link is valid
doi-link-valid [error]: DOI (Digital Object Identifier) link is valid
link-resolves [error]: Link URL resolves successfully
link-text-exists [error]: Link has non-empty text content
notebook-attachments-resolve [warn]: Jupyter notebook attachments resolve and decode successfully
notebook-output-copied [error]: Notebook cell output copies to disk successfully
mdast-snippet-imports [error]: MDAST snippet imports successfully
include-content-filters [warn]: Include directive filters apply correctly
include-content-loads [error]: Include directive loads target file successfully without circular dependencies
gated-nodes-join [error]: Conditional content nodes merge correctly
glossary-uses-definition-list [error]: Glossary directive contains a definition list
block-metadata-loads [error]: Block-level metadata loads and parses successfully
index-entries-resolve [warn]: Index entries resolve successfully
citation-is-unique [warn]: Citation identifier is unique across bibliography files
bib-file-exists [error]: Bibliography file specified in configuration exists
citation-renders [error]: Citation processes with citation-js successfully
code-metadata-lifted [warn]: Code cell metadata extracts without conflicts
code-metatags-valid [error]: Code cell tags are valid
code-lang-defined [warn]: Code block has a language specified
code-metadata-loads [error]: Code metadata loads successfully
inline-code-malformed [warn]: Inline code has either value or children but not both
inline-expression-renders [warn]: Inline expression evaluates successfully
static-file-copied [error]: Static file copies to output successfully
export-file-copied [error]: Export output file copies to public directory successfully
source-file-copied [error]: Source file copies to output successfully
template-file-copied [error]: Template file copies successfully
static-action-file-copied [error]: Static action file copies successfully
plugin-loads [error]: Plugin loads and executes without errors
container-children-valid [error]: Container has valid child elements
myst-json-valid [error]: MyST JSON file is valid
code-cell-executes [error]: Code cell executes without errors
inline-expression-executes [error]: Inline expression evaluates without errors

Pattern Matching in Keys¶

Keys support glob patterns, allowing you to match multiple URLs or paths with a single pattern. Patterns use the same glob syntax as many modern build tools:

* matches any characters except / (e.g., https://example.com/* matches https://example.com/page but not https://example.com/path/to/page)
** matches any characters including / (e.g., https://example.org/** matches all URLs under example.org)
? matches a single character (e.g., page? matches page1, page2, etc.)
*.example.com matches any subdomain (e.g., www.example.com, blog.example.com)
Brace expansion like {www,blog}.example.com matches either www.example.com or blog.example.com
Use {http,https}:// to match both HTTP and HTTPS protocols (e.g., {http,https}://api.example.com/** matches both protocol variants)

Common use cases:

To fail CI when there are missing links, you can use myst build --check-links --strict with the following example myst.yml configuration.

myst.yml

project:
  error_rules:
    # Match both HTTP and HTTPS for a domain
    - rule: link-resolves
      keys:
        - '{http,https}://legacy-api.mysite.com/**'
        - '{http,https}://staging.mysite.com/**'

This is particularly useful for ignoring groups of external links that may be blocked in CI environments or example URLs that don’t need to be checked.

Configuration and setup

Content frontmatter options

Configuration and setup

Table of Contents