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.
```{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.
The {include} directive¶
If a portion of your content is in a separate file that is not already included in your project you can use the include directive to parse and include that content.
This directive is helpful for including content snippets, such as a table, 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 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.
{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.
