Options

astro-myst has two places for options:

• the integration, myst() in astro.config, for settings shared by every MyST collection;
• the loader, mystLoader() in src/content.config.ts, for one collection.

The render settings are accepted by both; a loader’s value overrides the integration’s.

// astro.config.ts
import { defineConfig } from 'astro/config';
import myst from 'astro-myst';

export default defineConfig({
  integrations: [
    myst({
      project: { numbering: { headings: true }, math: { '\\dd': '\\mathrm{d}' } },
      styles: 'theme',
    }),
  ],
});

// src/content.config.ts
import { defineCollection } from 'astro:content';
import { mystLoader } from 'astro-myst/loaders';

export const collections = {
  book: defineCollection({
    loader: mystLoader({
      base: './src/content/book',
      toc: [{ file: 'index.md' }, { file: 'theory.md', children: [{ file: 'methods.md' }] }],
      route: '/',
      project: { numbering: { title: true, headings: true } },
    }),
  }),
};

Integration options#

myst(options), with the type MystOptions. All options are optional.

Without command, astro-myst runs the mystmd package installed in your project (or next to astro-myst), and falls back to a myst executable on the PATH.

project#

Anything the project: section of a myst.yml accepts: numbering, math macros, abbreviations, bibliography, references to other MyST sites, plugins, authors, license and so on. See MyST’s frontmatter reference.

myst({
  project: {
    numbering: { title: true, equation: { continue: true } },
    math: { '\\dd': '\\mathrm{d}' },
    abbreviations: { TLS: 'two-level system' },
    bibliography: ['src/content/references.bib'],
    references: { mystmd: 'https://mystmd.org/guide' },
  },
});

• File paths (bibliography, plugins, thumbnail, banner) are relative to the Astro project root. These files are watched in astro dev.
• Without a bibliography, the .bib files inside a collection’s base are used.
• Pages inherit some keys from the project, as in MyST: for example authors, date, license and numbering apply to every page that does not set its own.
• toc is ignored here: use the loader’s toc option.

styles#

Any other value is an error. See Styling and Components and styles.

scripts#

Small scripts the integration adds to every page. Each one acts only on MyST content in the page and does nothing elsewhere. scripts: false adds none; an object turns single scripts on or off, and keys you leave out keep their default.

myst({ scripts: { copyCode: true, mermaid: true } });

The scripts also run after Astro view transitions. They are the modules astro-myst/client/sync-tabs, astro-myst/client/copy-code and astro-myst/client/mermaid; to load one only on some pages, turn it off here and import it in a <script> there (see Browser scripts: astro-myst/client/*).

Loader options#

mystLoader(options), imported from astro-myst/loaders, with the type MystLoaderOptions. Only base is required. The loader needs the integration: without myst() in astro.config, it fails with an error saying so.

The loader’s project is merged with the integration’s at the top level only: a key you set here replaces the integration’s value for that key. For example, numbering: { title: true } on the loader replaces the whole numbering of the integration.

pattern#

By default, Markdown files and notebooks become entries, except those whose name starts with _. Use that prefix for snippets that pages only {include}. Folders such as node_modules, _build, .git and .ipynb_checkpoints are always ignored.

LaTeX files are not included by default. Add them to the pattern, or list them in toc:

mystLoader({ base: './src/content/paper', pattern: '**/[^_]*.{md,ipynb,tex}' });

Render settings#

These settings control how MyST content becomes HTML. Set them on the integration for every collection, or on a loader for one collection.

Behaviour in astro dev#

The loader watches base, extraInputs and the files that project points to (bibliographies, plugins). Any change recompiles the whole collection, so numbering and references stay consistent on every page, and Astro updates the pages. If a rebuild fails, the error is logged and the previous pages stay available. In astro build, a failed compilation fails the build with a message starting with [astro-myst].

Migrating from 0.1#

astro-myst 0.2 replaces myst.yml with options in your Astro config and makes the loader work like glob(). The table maps every option and field of 0.1 to its replacement. See also Getting started for the upgrade steps.