How to use sections in a myst article site?

[matthewfeickert]

When writing a paper, like the SciPy 2024 proceedings, if you are working with collaborators it is often highly desirable/necessary to split the paper text out into multiple files so that you do not continually encountere merge conflicts when writing asynchronously in a PR-based workflow. In LaTeX you would normally do this by using \include or \input directives like

...
\abstract{%
 \input{src/abstract}
}
%
\maketitle
%

\input{src/introduction.tex}

...

\input{src/conclusions.tex}
...

In the Jupyter Book Structure the Table of Contents docs it shows that you can structure a single page article from multiple input files using a _toc.yml file structure like

format: jb-article
root: index
sections:
- file: path/to/chapter1
- file: path/to/chapter2

and the --builder singlehtml option to jupyter-book build.

However, when trying to do this with mystmd v1.2.4 there doesn't seem to be this option for myst start or myst build. If in myst.yml a user is using

...
site:
  template: article-theme

is it possible to create a multiple input file paper? So something akin to changing

\input{src/introduction.tex}

...

\input{src/conclusions.tex}

for

...
sections:
- file: introduction.md
...
- file: conclusions.md

?

Relevant GitHub Issues and PRs

• feat: Split paper outline into section files matthewfeickert/draft-scipy-2024-proceedings-submission#13

[agoose77]

I'm AFK from my Linux machine at the moment, but I'm pretty sure that you can use the include directive for this. We also support \input in LaTeX if you want to use LaTeX-only!

[matthewfeickert]

Yes! Thank you @agoose77. Indeed just

:::{include} introduction.md
:::

in the main document does exactly what I wanted. 🚀

For others like me, c.f. https://mystmd.org/guide/embed#docs-include and https://mystmd.org/guide/directives#directive-include.

[choldgraf]

I added a little PR to document this use-case since it's fairly common, curious if you think this would have resolved your issue @matthewfeickert

• 📖 Document include for splitting a document across multiple parts #1232