You can embed labeled content (paragraphs, figures, notebook outputs, etc) across pages, allowing you to avoid re-writing the same information twice. You can also include files that are not in your project.
The {embed} directive¶
The {embed} directive allows you to insert snippets of content at the time a page is rendered.
See {the {embed} directive documentation} for details about all the arguments you can give to {embed}.
The {embed} directive can be used like so:
```{embed} #myLabel
```
Figure 1:Here’s a cool figure.
Note that this works for any labeled item in your MyST document, including from other pages. For example, the following references the admonitions list in Callouts & Admonitions.
```{embed} #admonitions-list
```Table 1:Named admonitions that can be used as directives
🔵 {note} | 🟠 {attention} |
🔵 {important} | 🟠 {caution} |
🟢 {hint} | 🟠 {warning} |
🟢 {seealso} | 🔴 {danger} |
🟢 {tip} | 🔴 {error} |
The  short-hand¶
The embedding markdown shorthand lets you quickly embed content using the Markdown image syntax (see more about images). It can be used like so:
Figure 1:Here’s a cool figure.
Embed images into figures¶
If you have a labeled image in your documentation, you can embed it as a Figure so that it contains figure metadata (like a caption, or adding alt-text). To do so, use a label attached to an image instead of a filepath.
For example, we’ll define an image with a label below:
(nice-sunset)=
And embed it into a figure next with a new label:
```{figure} #nice-sunset
:label: sunset-figure
Here's a nice sunset with a caption!
```Figure 2:Here’s a nice sunset with a caption!
The new label can be referred to in this context, i.e. [@sunset-figure]: Figure 2, which refers to the new figure rather than the original image. This allows you to scroll to embedded content on the page, rather than jumping to the original document. Note that this is especially useful with embedding Jupyter Notebook outputs. For example:
This figure has been included from a Jupyter Notebook and can be referred to in cross-references through a different label. See Embed and Reuse Jupyter Outputs for more information.
Embed notebook content and outputs¶
You can embed notebook content (for example, images generated by running a cell). For instructions on how to embed notebook content, see Embed and Reuse Jupyter Outputs.
Embed from External MyST Projects¶
You can embed content from an external site, allowing you to re-use snippets of text, figures and tables, etc from other MyST projects. This is similar to external cross-references, which allow you to hover over a link and see the content on a different MyST site.
First, add references to your myst.yml:
project:
references:
spec: https://mystmd.org/specAdd references to your project configuration in your myst.yml, MyST will then provide access to all of content on those pages in links and embeds.
You can then refer to content in these sites in two ways:
The embed short hand:
The
{Embed directive}::::{embed} xref:spec#admonition :::
When you build your MyST project, the content that your #label points to will be embedded in-place of the directive.
The {include} directive¶
You can include multiple files into your MyST document as if they were all written in the same file.
This allows you to store content in separate files, and then weave them together at build time.
To do so, use the {include} directive.
This is also helpful for including content snippets, such as a table or an equation, that you want to keep in a different file on disk, but present as if it were one document. In addition to Markdown, MyST will also parse .ipynb, .tex, and .html.
See {the {include} directive documentation} for details about all the arguments you can give to {include}.
By default the file will be parsed using MyST, you can also set the file to be {include.literal}, which will show as a code-block; this is the same as using the {literalinclude} directive which is documented in Including Code Files.
Auto Reload & Circular Dependencies
If you are working with the auto-reload (e.g. myst start), the file dependencies are auto-reloaded.
Circular dependencies are not allowed and MyST will issue a warning and not render the recursion.
Math and abbreviation frontmatter from included files
When including a file that has frontmatter, only some of that frontmatter is used. For example, the math macros and abbreviations are brought up to the top level and will overwrite any macros or abbreviations that already exist.
For LaTeX, the commands like \newcommand and \renewcommand are shared in the same way that math macros are shared for markdown files.
{embed} vs. {include}¶
The {include} directive is very similar to {embed}, with a few key differences.
{include}and{literalinclude}- parses source files (e.g. text files on your filesystem) and inserts them into the document structure as if you had written the content in your target source file. These files are not listed in your project table of contents, and generally only contain snippets.
{embed}- Pulls any labelled MyST content or outputs already parsed in your project.
