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.