Automatically Generating a Table of Contents (TOC)

[raamdev]

---

KB Article Creation Checklist

• [x] Write initial draft for this KB Article; label this issue draft and either questions or tutorials
• [x] Add required YAML configuration
• [ ] Add Tags for this KB Article to the YAML config (see YAML Keys (Explained))
• [x] Edit and finalize draft for publishing (remove draft label, add draft-finalized label)
• [ ] Assign Issue to yourself and create Markdown file (remove draft-finalized label, add pending)
• [ ] Project Lead: Review and Publish KB Article (remove pending label, add published label)

title: Automatically Generating a Table of Contents (TOC)
categories: tutorials
tags: 
author: raamdev
github-issue: https://github.com/websharks/wp-kb-articles-kb/issues/5

---

The WP KB Articles plugin can automatically generate a TOC (Table of Contents) for you, based on the headers that it finds inside your article. This is especially useful for longer articles, as it provides an easy way of navigating the article and getting a quick overview.

Note: Automatic-TOC Generation is a Pro feature, available with WP KB Articles Pro.

To use this feature, you'll need to enable it. You can enable it on a per-article basis, or enable it globally. If you're using the WP KB Articles GitHub Integration, you can enable or disable this from within the YAML Front Matter configuration.

Step 1: Enable Automatic-TOC Generation

Automatic-TOC Generation is enabled by default, but you can control the global setting for this feature from Dashboard → KB Articles → Config. Options → TOC (Table of Contents). (This setting will apply to all KB Articles but the configuration can also been overwritten on a per-article basis; see below).

You can also enable or disable this functionality on a per-article basis. This is useful if, for example, you know that most articles will not need a Table of Contents, but some of the longer articles will.

If you disable Automatic-TOC Generation globally, you can enable it on a single article by adding a new Custom Field to the article with wp_kb_articles_toc_enable=true|false:

Step 2: Use Headers in your KB Articles

The Table of Contents will be generated using whatever Headers WP KB Articles finds in your article.

You can use HTML-style headers:

<h1>Nginx Configuration Title</h1>
<h2>Nginx Sub Title Regarding Something Else</h2>
...

Or ATX-style Markdown headers:

# Nginx Configuration Title
## Nginx Sub Title Regarding Something Else
...

Note that articles that don't contain any headers will be bypassed by the Automatic-TOC generation.

---

YAML Front Matter (GitHub Integration)

If you're using the GitHub Integration, you can control the Automatic-TOC generation on a per-article basis (no matter what the global config. option is), by adding a YAML config. field: toc-enable: true|false in a specific article.

---
toc-enable: true

---

Specifying toc-enable: true in the YAML Configuration in the Markdown file will tell WP KB Articles to enable Automatic-TOC generation for this article.

Again, specifying this on a per-article basis is only necessary if you want to override the global configuration (Dashboard → KB Articles → Config. Options → TOC (Table of Contents)).

[raamdev]

@jaswsinc Can you confirm that Automatic-TOC Generation is disabled by default?

[jaswrks]

Can you confirm that Automatic-TOC Generation is disabled by default?

Actually, it is enabled by default: https://github.com/websharks/wp-kb-articles-pro/blob/000000-dev/wp-kb-articles-pro/plugin.inc.php#L412

[jaswrks]

Also, this is a pro feature. It is not available in the lite version.

[raamdev]

Actually, it is enabled by default

Thank you. Article updated.

Also, this is a pro feature. It is not available in the lite version.

Thank you, I mentioned this at the top of the article.