Every setting explained
Everything lives on one page: Settings, then Table of Contents. There are no sub-pages and nothing is hidden behind a tab you have to find. Each setting has a one-line note under it in the admin; this page says a little more and gives examples. Reading time: eight minutes.
The page is in four groups, in the order you would think about them: where the list appears, what it lists, how it looks, and what the links are called.
A few settings only appear when they apply. “After how many paragraphs” means nothing until you have chosen to place the list after a set number of paragraphs, so it is not on the screen until you do. The same goes for the chosen width, the five colours, the two fold settings and what a number ends with. They are all described below in the order they appear on the page; if one of them is not on your screen, set the field above it and it arrives. Nothing is lost by hiding: a setting you had chosen earlier keeps its value and comes back exactly as you left it.
Where it appears
On. Every post and page of a ticked kind gets a list, in the place chosen below.
Turn it off if you would rather place every list yourself with the block, the shortcode or the widget. Nothing else in this group applies then.
| Choose | What happens |
|---|---|
| Before the first heading | The list sits after your opening paragraphs and before the first section. This is what most posts want, and the default. |
| After the first paragraph | Straight after one paragraph, whatever follows it. |
| After a set number of paragraphs | The same, with the number you choose below. |
| At the top | The first thing in the post, above everything. |
| At the bottom | The last thing. Useful for reference pages people scroll to the end of. |
“Before the first heading” and “At the top” are the same thing for a post that opens with a heading.
Counted from the top of the post. One to fifty. It only appears when “Where to put it” is set to “After a set number of paragraphs”.
Posts and pages to start with. Every other kind of content your site has, from other plugins or from your theme, is listed here too, so a shop can give its product pages a list without touching anything else.
On. Every heading gets its own link, even on a post too short for a list, and on kinds of content you did not tick above.
This costs nothing and it is what makes “link to this bit” work across your whole site. Turn it off only if another plugin is already adding ids to your headings and you would rather it kept doing so.
Which kinds of content get the Table of Contents panel in the editor, where a writer can change the list for one post. Set this to nothing if you would rather writers could not.
What it lists
h2 and h3 to start with. Tick the levels your posts actually use.
Two things to know. Your post title is an h1, so h1 is never listed, however your theme marks it up. And a heading at a level you leave unticked gets no anchor either, so the list and the links always agree with one another.
Three. A post with fewer headings than this gets no list.
A list of two entries tells a reader nothing they could not see by scrolling, so this is a judgement about usefulness rather than a limit. Raise it to four or five if your posts are mostly short.
On. Headings are indented under the heading above them, so an h3 sits under its h2.
Off puts every heading at the same level, which reads better when a post uses h2 and h3 interchangeably rather than as a hierarchy.
| Choose | Looks like |
|---|---|
| None | Entries with no marker at all. |
| 1. 2. 3. | Every entry numbered straight through, whatever its level. |
| 1. 1.1 1.2 | Numbered by level, so a sub-heading carries its parent’s number. The default. |
| I. II. III. | Roman, straight through. |
| I. I.I I.II | Roman, by level. |
| i. ii. iii. | Roman in lower case, straight through. |
| i. i.i i.ii | Roman in lower case, by level. |
| Round, Hollow, Square, Dash | A bullet instead of a number. |
The numbers are real text in the page. A reader can copy them along with the entry, and a screen reader reads them out. They are not drawn by the stylesheet, which is how most plugins do it and is why copying a list from those plugins loses the numbers.
The bullets are the other way round, on purpose. Those are the browser’s own list markers rather than text we write. A number is something a reader refers to: they say “see 3.1”, they copy it, and a screen reader should read it. A bullet is decoration, and a screen reader announcing “bullet” before each of twenty entries is noise rather than help. So numbers are text and bullets are markers, and each is the right kind of thing for what it is.
Nothing, a full stop, a bracket or a dash. For example 1.3).
One per line. A heading whose text matches a line here is left out of the list and gets no anchor.
Use an asterisk for “any text here”:
“`
Related *
About the author
Share this *
“`
This is how you keep the furniture at the bottom of a post out of its contents list.
esd-toc-skip to start with. Add that class to a heading in the editor’s Advanced panel and that one heading is left out, without having to describe it by its words.
How it looks and behaves
“Contents”. Put your own words in, or leave it empty for no title at all.
An empty title and Collapsible on cannot both be true: with nothing to press, there would be no way to unfold the list, so the fold is dropped and the list stays open.
On. The reader can fold the list away.
The whole title is the control, not just the arrow, and it works with no JavaScript at all: this is the <details> element, a part of HTML that every browser in use has supported for years. It also means the fold survives a page builder, a caching plugin, a script error elsewhere on the page, and a reader who blocks JavaScript.
| Choose | What it looks like |
|---|---|
| Just after the title | The arrow sits beside the words, pointing down when the list is open. The default. |
| Before the title | Ahead of the words, pointing along the line when folded and down when open, the way a file tree behaves. |
| At the far end of the row | Pushed to the opposite end of the list’s width. |
| No arrow | The title alone. |
Whichever you choose, the whole title is still the control. The arrow is there to say the list folds, not to be pressed on its own.
Off. Turn it on to show only the title until the reader opens it.
We suggest leaving it off. Most readers never press a closed list, so a list that starts closed is close to no list at all. The exception is a very long reference page where the list would fill the screen.
Off. Turn it on to show the list only on screens wider than 600 pixels.
We suggest leaving it off, and the suggestion is on the setting itself: a long post on a phone is exactly where a contents list earns its keep.
Auto, which means as wide as the text it sits in. Full width stretches it; “A width I choose” takes a number and a unit, in pixels or per cent, which is mostly useful with the alignment below.
| Choose | What happens |
|---|---|
| In the flow, on its own | The list is a block like a paragraph. The default. |
| Left, with the text wrapping round it | The list floats left and the post flows round it. |
| Right, with the text wrapping round it | The same, on the right. |
| Centred | Centred, which only looks different when the width is less than full. |
A floating list goes back into the flow on a phone, where there is no room beside it. You do not have to do anything to make that happen.
| Choose | What it does |
|---|---|
| None, take everything from my theme | No background, no border. The list takes its colours and its type from your theme. The default, and what we recommend. |
| Light | A pale grey panel with a thin border. |
| Dark | A dark panel with light text. |
| My own colours | The five colours below. |
None is recommended for one reason: it matches your theme on every page, including the pages you build next year with a different theme.
Background, border, title, link, and link when hovered. Used only when Box is “My own colours”. Leave one empty to let your theme decide it, which is how you get, say, a coloured panel with your theme’s own link colour.
On. The page slides to the heading rather than jumping to it.
This is one line of CSS, not a script, and it turns itself off for readers who have asked their device for less motion. You do not have to think about that.
Zero. Raise it, in pixels, if your theme has a bar fixed to the top of the screen that would otherwise cover the heading the reader just jumped to.
Measure the bar’s height and use that. If you are not sure, 80 is a reasonable guess for most themes with a fixed header.
Added to the list’s outer element, so you can style one site’s list without touching the plugin. Separate several with spaces.
Off. Turn it on and the plugin prints no CSS at all.
The list is still a proper nested list with proper links; it simply arrives with none of our layout, for anyone who would rather write their own. Note that the fold still works, because the fold is HTML rather than CSS.
Anchors
An anchor is the #something on the end of a link that points at one heading. These settings decide what those are called, and they are the only settings on the page you should think twice about.
| Choose | A heading called “How it works” becomes |
|---|---|
| Dashes and lower case | #how-it-works. The default, and what WordPress itself uses. |
| Underscores, as the heading | #How_it_works. What LuckyWP does. |
| Underscores, keeping accented letters | #Café_floors rather than #Cafe_floors. |
| Easy Table of Contents style | That plugin’s own rules, which differ in how repeated headings are numbered. |
| Numbered | #section-1, by position rather than by words. |
Changing this changes every link anyone has ever shared. A link in somebody’s email, in a Google result, in another site’s article: all of them point at the old name and all of them stop working. So change it only when you are moving from another plugin, and in that case let the move do it for you, from the Move from another plugin tab, which sets this and everything else to match what your old plugin was producing.
Convert to lower case, and replace underscores with dashes. These are the two switches the other plugins offer, kept so that a move from one of them can reproduce exactly what it was doing. They change nothing when the format is already dashes and lower case.
On. Each post remembers the anchors it has already published, so a link someone shared keeps working after you reword the heading.
We have not found another contents plugin that does this. How the list is built explains how it decides that a reworded heading is the same heading. Deleting the plugin removes what it remembered, along with everything else it ever stored.
Off. Turn it on and those three shortcodes, left behind in your posts by another plugin, show one of our lists instead of printing nothing.
We only ever answer a shortcode whose own plugin is switched off. While LuckyWP or Easy Table of Contents is still running, its shortcode is its own and we do not touch it.
The panel in the editor
Every post of a ticked kind has a Table of Contents panel in the editor sidebar. Everything in it is “use the site setting” until you change it, and a post only remembers the things you did change.
- Show a list on this post. Yes or no, overriding the site setting either way.
- Title. Empty uses the site’s.
- Where to put it. The same choices as the site setting, minus “after a set number of paragraphs”.
- Heading levels. None ticked uses the site setting.
- Minimum headings. Empty uses the site’s.
- Skip headings matching. Empty uses the site’s. One per line, as above.
The block, the shortcode and the widget
Three ways to put a list exactly where you want it. All three list the post they are in, and all three work whether or not automatic placement is on.
The block, called Table of contents, in the inserter. It has a title, heading levels and whether it folds, and it uses WordPress’s own alignment and margin controls.
The shortcode, [essence_toc], for page builders and for anywhere a block cannot go. Every attribute is optional and anything you leave out comes from the settings page:
“`
[essence_toc title=”In this guide” levels=”2,3,4″ numbering=”decimal_nested”
suffix=”)” nested=”yes” collapsible=”yes” collapsed=”no” arrow=”before”
box=”light” align=”right” width=”280px” min=”2″ class=”my-toc”]
“`
| Attribute | Takes |
|---|---|
title | Any text. An empty title means no title. |
levels | Levels, as in 2,3,4. |
min | A number. The minimum headings for this list only. |
numbering | none, decimal, decimal_nested, roman, roman_nested, roman_lower, roman_lower_nested, bullet_disc, bullet_circle, bullet_square, bullet_dash. |
suffix | Nothing, ., ) or -. |
nested | yes or no. |
collapsible | yes or no. |
collapsed | yes or no. |
arrow | after, before, end, none. |
box | none, light, dark, custom. |
align | none, left, right, center. |
width | auto, full, or a size such as 280px or 40%. |
class | Extra classes, separated by spaces. |
The widget, called Table of Contents, for themes with a classic sidebar. It takes a title, and an empty title uses the one from the settings page.