Static Sites with Sphinx and Markdown Transcripts
Chapter: More Authoring
Lecture: TOC: Table of Contents
Login or
purchase this course
to watch this video and the rest of the course contents.
0:00
With Sphinx. It isn't enough to just leave a file in a directory.
0:04
You need to include it in what Sphinx calls a 'Table of Contents'.
0:10
So let's take a look at the toctree directive,
0:15
then explain what's going on behind the scenes and then explain why you should care.
0:21
Here is the Sphinx documentation page for the toctree directive and it explains a little
0:29
bit more about the purpose of it.
0:31
The purpose is to link files most of the time in a directory in a particular
0:37
order, including and excluding what you want to go into the generated output.
0:44
And you can see some of the options that are included with it.
0:48
You can add things such as captions and names and globs and we're gonna go over
0:54
a couple of these back in our 'index.md' file.
1:00
We already have a toctree director of that.
1:03
We converted to the Myst Markdown syntax in a previous step.
1:09
It is done as a code fence with the triple back tick.
1:14
And then since the first argument of the code fences in a curly bracket,
1:19
that means it's a tapping directly into a sphinx directive.
1:23
The toctree directive, we're passing to configuration options to the directive.
1:30
We're going to set how deep to go in the table of contents.
1:34
And what this does is each entry in the table of contents has headings and sub
1:39
headings and subheadings and all of those can be plucked out and inserted into the
1:46
hierarchy of the table of contents.
1:48
So you could jump directly to a heading from the table of contents and then the
1:53
second one we're using is a caption where we set the information for the caption,
1:58
we put it in quotes because there's a colon that we wanted to have.
2:02
Then we have a blank space and then we have a listing of items that are
2:08
supposed to go into this table of contents.
2:11
These are paths, they can have relative and absolute slashes and dot thoughts and
2:20
things in front of them and order matters.
2:24
The entry that you put these is the entry is the order that they will appear
2:29
in the rendered output. It also has some kind of semantic meeting as well.
2:35
So briefly if we wanted to change the caption that was displayed,
2:39
we could edit this if we didn't want to manually list everything in a very large
2:46
directory if order didn't matter if we want a convenience over meaning and structure or something
2:52
there is a glob that is supported so I could put as an option to
2:58
turn on globing and then here just say asterisk or some kind of glob
3:04
character and I could have multiple lines on this to do different kinds of things for
3:08
this. What if we didn't like the syntax that was the syntax for these options
3:17
This restructured text, what we want to YAML,
3:21
MyST supports, YAML to send configuration arguments to directives and it would look like this
3:28
kinda like front matter in markdown documents.
3:31
It's a triple dash and then a pile of YAML and another triple dash and a
3:36
blank line and then everything else is the body.
3:40
So in this case we've basically converted key value pairs from the restructured text syntax into
3:49
key value pairs for YAML now is wrap up.
3:54
Why do we care about table of contents?
3:56
Why do all this extra work?
3:57
Well Sphinx is about structure more than how it looks because it renders to multiple kinds
4:03
of outputs and it has a lot of cool facilities for linking and structure and all
4:10
that kind of stuff and so it cares about structure within a document but also between
4:16
documents and that's where the toctree comes in play.
4:19
You can have a toctree to a range of information hierarchy.
4:23
You can even have multiple toctrees in the same document.