aleung / gitbook-plugin-page-toc

Add Table of Contents (TOC) to every page in your GitBook.

gitbook-plugin-page-toc

This plugin adds a table of contents (TOC) to each page in your Gitbook. You can set whether the TOC appears on all pages by default, and you can enable or disable the TOC on individual pages to override the default.

Install

Add the plugin to your book.json:

{
  "plugins": [ "page-toc" ],
  "pluginsConfig": {
    "page-toc": {
      "selector": ".markdown-section h1, .markdown-section h2, .markdown-section h3, .markdown-section h4",
      "position": "before-first",
      "showByDefault": true
    }
  }
}

Configuration

• selector : CSS selector to select the elements to put anchors on
  • Default: .markdown-section h1, .markdown-section h2, .markdown-section h3, .markdown-section h4, which include headings from level 1 to level 4.
• position : Position of TOC
  • Allowed values:
    • before-first (default) : Before the first heading
    • top : On top of the page
• showByDefault: Whether to show the TOC on all pages by default.
  • Default: true.

Use

To show a TOC in one of your pages, either set the showByDefault parameter to true in your book.json, or add the front matter item showToc: true to the top of the Markdown file like this:

---
showToc: true
---
# My interesting page that has a TOC

If you have the showByDefault parameter set to true and you want to hide the TOC on a page, add the front matter item showToc: false to the top of the Markdown file like this:

---
showToc: false
---
# My interesting page that does not have a TOC

The page-specific front matter overrides the showByDefault parameter.

CSS Customization

The TOC elements have class attribute .page-toc. You can override the styles in styles/website.css.

gitbook-plugin-page-toc's Issues

Internationalization title.

First of all I want to congratulate the work was very good.

I am writing a booklet in Portuguese, and would like to change the title box where the ToC is displayed. Changing the text to Portuguese.

not compatible with gitbook 3

Configuration for page-toc .markdown fails

"selector": ".markdown-section h2"

I was hoping to only show the h2 items in the toc. So I used this configuration but it fails. It keeps adding the <h1> values.

GitBook Community in Google+

Hi aleung,

I am Aleen (https://github.com/aleen42) , and the founder of GitBook Community in Google+: https://plus.google.com/communities/110696788983472771007, which aims to sharing books or plugins of GitBook, talking anything about it as well. Here I am sincerely inviting you to join us. 👊

Add possibility to disable for specific pages

Thanks for this plugin I use in various gitbooks.

A cool capacity would be to allow disabling TOC for specific pages,. It could be with a specific tag like {% notoc %} or with an option in book.json/pluginsConfig/page-toc/"exclude": "page.md,...".

use case is for pages with a lot of titles, so the TOC is too huge to be usable.

Allow configuring a selector for the position

Hi!

I can pull request it in a few minutes, will you accept it?