From cf6627bc4efb82c34713f76457d16be62f8901b7 Mon Sep 17 00:00:00 2001 From: choldgraf Date: Thu, 23 May 2024 20:02:04 -0700 Subject: [PATCH 1/2] Document include --- docs/documents-exports.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/documents-exports.md b/docs/documents-exports.md index 4db82ed24..cfa001a1d 100644 --- a/docs/documents-exports.md +++ b/docs/documents-exports.md @@ -56,3 +56,10 @@ The following table shows the available properties for each export. You must def ```{seealso} Exposing Exports as Downloads You can also include exported documents as downloads in your site, see [](./website-downloads.md). ``` + +## Split your document across multiple content files + +When writing longer documents like manuscripts, it's common to write your document in multiple parts and then stitch them together into a single narrative. +You can accomplish this in MyST with the {myst:directive}`include` directive. + +See [](#docs:include) for more information. From 527f58b5516e607188f1a8e77d1e61ed1f866fc0 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 23 May 2024 21:41:08 -0700 Subject: [PATCH 2/2] Include example --- docs/embed.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/embed.md b/docs/embed.md index bd96d7034..0f146628a 100644 --- a/docs/embed.md +++ b/docs/embed.md @@ -146,8 +146,11 @@ The following content is embedded from `![](xref:spec#admonition)`: ## The {myst:directive}`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 {myst:directive}`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`. +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 {myst:directive}`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 {myst:directive}`the {include} directive documentation ` for details about all the arguments you can give to `{include}`.