Organising content

Organising content#

Sphinx allows you to organise your content into multiple documents, and to include content from other documents.

This section describes how to do this with MyST Markdown.

1.  Document structure#

Single MyST Markdown documents are structured using headings.

All headings at the root level of the document are included in the Table of Contents (ToC) for that page.

Many HTML themes will already include this ToC in a sidebar, but you can also include it in the main content of the page using the contents directive:

```{contents} Table of Contents
:depth: 3
```

Options:

depth:

Can be used to specify the depth of the ToC.

local:

Can be used to only include headings in the current section of the document.

backlinks:

Can be used to include a link to the ToC at the end of each section.

class:

Is available to add a custom CSS class to the ToC.

Warning

Because the structure of the document is determined by the headings, it is problematic to have “non-consecutive” headings in a document, such as:

# Heading 1
### Heading 3

If you wish to include such a heading, you can use the attrs_block extension to wrap the heading in a div, so that it is not included in the ToC:

# Heading 1
:::
### Heading 3
:::

Setting a title in front-matter

Added in version 0.17.0.

The myst_title_to_header = True configuration allows for a title key to be present in the document front matter.

This will then be used as the document’s header (parsed as Markdown). For example:

---
title: My Title with *emphasis*
---

would be equivalent to:

# My Title with *emphasis*

2.  Inserting other documents directly into the current document#

The include directive allows you to insert the contents of another document directly into the flow of the current document.

See also

The literalinclude directive, for including source code from files.

```{literalinclude} example.txt
```

```{include} example.txt
```

Hallo
there
you!

Hallo there you!

The following options allow you to include only part of a document:

start-line:

Only the content starting from this line number will be included (numbering starts at 1, and negative count from the end)

end-line:

Only the content up to (but excluding) this line will be included.

start-after:

Only the content after the first occurrence of the specified text will be included.

end-before:

Only the content before the first occurrence of the specified text (but after any after text) will be included.

```{literalinclude} example.txt
```

```{include} example.txt
:start-line: 1
:end-line: 2
```

```{include} example.txt
:start-after: Hallo
:end-before: you!
```

Hallo
there
you!

there

there

The following options allow you to modify the content of the included document, to make it relative to the location that it is being inserted:

heading-offset:

Offset all the heading levels by this positive integer, e.g. changing # to ####

relative-docs:

Make Markdown file references, relative to the current document, if they start with a certain prefix

relative-images:

Make Markdown image references, relative to the current document

```{literalinclude} examples/example_relative_include.txt
```

```{include} examples/example_relative_include.txt
:heading-offset: 3
:relative-docs: ..
:relative-images:
```

# My heading

[](../typography.md)
![alt](../img/fun-fish.png){w=50}

My heading

Typography alt

Additional options:

encoding:

The text encoding of the external file

Including to/from reStructuredText files

As explained in this section, all MyST directives will parse their content as Markdown. So to include rST, we must first “wrap” the directive in the eval-rst directive:

```{eval-rst}
.. include:: ../faq/snippets/include-rst.rst
```

Hallo I’m from an rST file, with a reference.

To include a MyST file within a ReStructuredText file, we can use the parser option of the include directive:

.. include:: include.md
   :parser: myst_parser.sphinx_

Important

The parser option requires docutils>=0.17

3.  Using toctree to include other documents as children#

To structure a project, with multiple documents, the toctree directive is utilised.

The designate documents as children of the current document, building up a nested hierarchy of documents starting from a root_doc.

```{toctree}
examples/content_child1.md
examples/content_child2.md
```

The toctree has options:

glob:

Indicates that all entries are then matched against the list of available documents, and matches are inserted into the list alphabetically

The following options to control how it is displayed within the document:

caption:

A title for this toctree

hidden:

Do not show within the document

includehidden:

Included child hidden toctree entries

maxdepth:

The depth of document sub-headings shown

titlesonly:

Only show the first top-level heading

reversed:

Reverse the order of the entries in the list

Additional options:

name:

Allow the toctree to be referenced

numbered:

Number all headings in children. If an integer is specified, then this is the depth to number down to

Tip

Sub-toctrees are automatically numbered, so don’t give the :numbered: flag to those