Table of Contents

|

What is the best way to work with a Table of Contents in the Homebrewery?

Homebrewery’s Table of Contents snippet generally works by collecting all of the headers used in your brew and the manipulates them into a list of links. It only does this at the initial generation of your ToC.

This means two things:

  • You should use headers appropriately.
  • Generating your Table of Contents should be one of the last things you do.

So let’s hit those two things, and then dive deeper into the finer ToC-related snippets.

Using Headers

Use headers in a consistent, hierarchal manner– said another way, don’t use them based on their styled appearance. That PHB theme h3/### header may have a cool column-spanning underline and a nice size, but it shouldn’t be used only for that reason. Headers should build from h1 to h2 to h3 and so as you go deeper into the outline depth.

Getting the hierarchy just right isn’t always as easy as it would seem. For starters, you have to decide if the main title of your brew is a proper header (h1), or if you consider it outside the content flow and have your h1 start as the opening header of your actual content. As an example, I would not consider the title of a D&D book a “header”, but I would consider the title of a “Part” a h1 header (Part 1: …, Part 2: …).

This theory of header structure can be examined more closely, as well, but for the purposes of this article I think the point has been made: use headers semantically, not stylistically. When you do, ToC generation by default grabs any headers from h1 to h3 and adds them to the ToC. This can be expanded to deeper levels of headers with the other snippets in the Table of Contents menu, which we’ll come back to.

Generating the Table of Contents

Clicking the Table of Contents snippet will run the generator immediately and spit out the result at your cursor. This means that if you generate it before you’ve written anything, you basically will get an empty page.

If you write half your project, and then decide to generate a ToC, you’ll get some results on the page, but then you’ll have to delete those results and run it again later when you have a complete brew.

If your brew is very long, with many headers, you might find that the whole list won’t fit on a single page. In that case you will want to delete what was just generated, create a new blank page (so that you have the necessary two or more pages you need to fit the full ToC), and run the generator again. This ensures that you have the space needed for the list, but you’ve still got the correct page numbers in your entries, adjusted for the additional page(s). Then manually split the list across the two pages.

The above example has to skip the page break because this editor doesn’t do multi-page documents, but you can see where that break would be, and pasting into homebrewery as-is would work. This example does show how a table of contents could be split across multiple pages, including how to continue a nested list from one page to the next using a single - to fake a list entry.

General rule is to not worry about creating your table of contents until you are nearly finished with your project, but do mind your headers right from the very start.

Managing Exceptions

There are times when either the generator doesn’t behave exactly how you would expect by default, and other times when you might want to change the rules yourself a bit.

Excluding Headers from Table of Contents

By default, the PHB theme does not count the headers inside a Monster Stat Block when building a table of contents. It just skips over the normal h2 and h3 headers that are typically within those blocks. This happens because of a certain css declaration:

Anything inside a .monster block will be excluded from the table of contents. Keep this in mind, because we can use the same declaration in other blocks if we wish. Below is an example of doing that via inline CSS declaration– the same could be done in the Style/CSS Editor– and a table of contents would be generated without these headers:

Including Headers in Table of Contents

Conversely, if you want to be sure that additional header depths are included in a generated table of contents, you can add a set of classes to your blocks: tocDepthH3 to tocDepthH6. Anything inside a block/div with one of these classes will have it’s internal headers added to the table up to that depth.

For example, if you had an appendix at the back of your book that is a bestiary you might want to include at least the monster names in your table of contents. By default, those names wouldn’t appear because of the --TOC: exclude. And just unsetting that variable with --TOC: unset wouldn’t help, because then all the headers inside the monster stat block would be compiled, including the ### Actions.

Starting at the start of the bestiary, right where the first \page break is, I’d add the {tocDepthH2} class to the page via the injection syntax. Use a header at the top, # Bestiary for example, then add my monster stat blocks the normal way.

This will generate a table of contents that includes the monster names:

Closing

To sum it all up, the generator runs immediately and grabs all your headers from h1 to h3 by default, with some exceptions. You can clear those exceptions, or create and manage your own. But most importantly, just know that headers have a semantic value that is important to consider, and the appearance of the headers can be changed in the Style editor with CSS to make them look like anything else.

Resources