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