The Table of Contents is the left-hand navigation for your site. It can either be auto-generated, following some simple heuristics described below, or can be explicitly defined in a _toc.yml
using the jb-book
format.
Generating a Table of Contents¶
By default the table of contents is left implicit, and follows rules laid out in the next section. To make this table of contents explicit, you can call:
myst init --write-toc
This will create a _toc.yml
in the current directory, you can read more about the table of contents format below.
Auto-generating a Table of Contents¶
When there is no _toc.yml
defined an implicit table of contents is defined by the file system structure. All markdown and notebook files will be found in the working directory and all sub-directories. Filenames are not treated as case sensitive, and files are listed before folders. All hidden directories are ignored (e.g. .git
) and the _build
directory is also ignored.
The ordering of the table of contents will sort alphabetically as well as order by number, ensuring that, for example, chapter10
comes after chapter9
.
Filename Transformations¶
The filenames will also be transformed into url-friendly “slugs” that: remove preceding numbers (unless they are year-like, e.g. 1988-02 or 2022); rename any non-url characters (spaces, underscores, etc.) to -
; lowercase the filename; remove any file extensions (e.g. .md
or .ipynb
); and keep the slug less than 50 characters. If there are duplicates, these will be enumerated with a trailing number (e.g. readme-1
).
01-notebook.ipynb
will becomenotebook
2021_02_presentation.md
will remain2021-02-presentation
Title Transformations¶
If a title is not provided by a notebook or markdown document in the front matter or first heading, the filename is used. The filename is transformed to a title by splitting on camel case, replacing -
or _
with spaces, and transforming to title-case.
01_MyNotebook.ipynb
becomesMy Notebook
my_article.md
becomesMy Article
Root Page¶
The “root” of a site is the page displayed when someone browses to the index of your site without any pathname. The CLI will choose the root file in the following order:
index.md
README.md
main.md
- The first
.md
file found alphabetically index.ipynb
README.ipynb
main.ipynb
- The first
.ipynb
file found alphabetically
Excluding Files¶
If there are markdown or notebook files within a project folder that you do not want included in your project, you may list these in the myst.yml
project frontmatter under exclude
. For example, to ignore a single file notes.md
, all notebooks in the folder hpc/
, and all files named ignore.md
:
project:
exclude:
- notes.md
- hpc/*.ipynb
- '**/ignore.md'
Additionally, files excluded in this way will also not be watched during myst start
. This may be useful if you have a folder with many thousands of files that causes the myst start
watch task to crash. For example, in the data/
directory, there may be no markdown and no notebooks but 100,000 small data files:
project:
exclude: data/**
Note that when these files are excluded, they can still be specifically referenced by other files in your project (e.g. in an include directives
or as a download), however, a change in those files will not trigger a build. An alternative in this case is to generate a table of contents (see Table of Contents). By default hidden folders (those starting with .
, like .git
), _build
and node_modules
are excluded.
Defining a _toc.yml
using Jupyter Book’s format¶
The _toc.yml
can be defined for a site, and uses the format describe by Jupyter Book, the documentation for the format is fully described in Jupyter Book. Briefly, it defines a format
as jb-book
and can list a number of chapters
with files. The file paths are relative to your _toc.yml
file and can optionally include the extension.
format: jb-book
root: index
chapters:
- file: path/to/chapter1
- file: path/to/chapter2
For larger books, you can group the content into parts
. Each part
has a caption
and a list of chapters
files can define children using a list of sections
.
format: jb-book
root: index
parts:
- caption: Name of Part 1
chapters:
- file: path/to/part1/chapter1
- file: path/to/part1/chapter2
sections:
- file: path/to/part1/chapter2/section1
- caption: Name of Part 2
chapters:
- file: path/to/part2/chapter1
- file: path/to/part2/chapter2
Nesting of Files in URLs¶
MyST can have any level of nesting in a file-system of your project, however, when it is displayed in the URL in mystmd
, these nesting will be flattened to have a single “slug” that is contained in the project.
project/folder2/01_my_article.md
becomesproject/my-article
All internal links will automatically be updated, and there is a file
property that is exported as metadata. Add .json
to the end of any url in your site to see the full data of the page.