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:

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
:::

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

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