{"id":47925476,"url":"https://github.com/fzankl/gitbook-plugin-intopic-toc","last_synced_at":"2026-04-04T06:29:28.854Z","repository":{"id":42885406,"uuid":"164215751","full_name":"fzankl/gitbook-plugin-intopic-toc","owner":"fzankl","description":"GitBook Plugin to add inline table of contents (TOC) to each page using sticky and scrollspy effects.","archived":false,"fork":false,"pushed_at":"2023-07-18T21:59:46.000Z","size":355,"stargazers_count":32,"open_issues_count":2,"forks_count":10,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-03T01:25:01.494Z","etag":null,"topics":["anchor","gitbook","gitbook-plugin","scrollspy","sticky","table-of-contents","toc"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fzankl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-05T13:06:57.000Z","updated_at":"2025-09-07T17:53:30.000Z","dependencies_parsed_at":"2024-06-18T22:50:33.479Z","dependency_job_id":"f1b853e7-050f-4d67-bed4-8dc2ed1c5a24","html_url":"https://github.com/fzankl/gitbook-plugin-intopic-toc","commit_stats":null,"previous_names":["zanfab/gitbook-plugin-intopic-toc"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/fzankl/gitbook-plugin-intopic-toc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fzankl%2Fgitbook-plugin-intopic-toc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fzankl%2Fgitbook-plugin-intopic-toc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fzankl%2Fgitbook-plugin-intopic-toc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fzankl%2Fgitbook-plugin-intopic-toc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fzankl","download_url":"https://codeload.github.com/fzankl/gitbook-plugin-intopic-toc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fzankl%2Fgitbook-plugin-intopic-toc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31390164,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T04:26:24.776Z","status":"ssl_error","status_checked_at":"2026-04-04T04:23:34.147Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anchor","gitbook","gitbook-plugin","scrollspy","sticky","table-of-contents","toc"],"created_at":"2026-04-04T06:29:28.324Z","updated_at":"2026-04-04T06:29:28.845Z","avatar_url":"https://github.com/fzankl.png","language":"JavaScript","readme":"# GitBook plugin: InTopic TOC\r\n\r\n[![Build Status](https://github.com/fzankl/gitbook-plugin-intopic-toc/actions/workflows/main.yml/badge.svg)](https://github.com/fzankl/gitbook-plugin-intopic-toc)\r\n[![npm version](https://img.shields.io/npm/v/gitbook-plugin-intopic-toc/latest.svg)](https://www.npmjs.com/package/gitbook-plugin-intopic-toc)\r\n[![npm Downloads](https://img.shields.io/npm/dt/gitbook-plugin-intopic-toc.svg)](https://www.npmjs.com/package/gitbook-plugin-intopic-toc)\r\n\r\nThis GitBook plugin adds an inline table of contents (TOC) to each page based on configurable selectors. Inline TOC can be enabled or disabled by default or on individual pages. TOC is placed on the right side and moves to top for smaller devices automatically.\r\n\r\nInline TOC stays at the top of the page when scrolling using a sticky effect. Current position is highlighted by a scrollspy effect.\r\n\r\n![Inline TOC in desktop and mobile mode](https://user-images.githubusercontent.com/44210522/79138004-0df58180-7db4-11ea-9df4-95cd42e1f251.gif)\r\n\r\nPlugin uses [gumshoe](https://github.com/cferdinandi/gumshoe) and [anchorjs](https://github.com/bryanbraun/anchorjs) to implement functionality.\r\n\r\n## Installation\r\n\r\n### Step #1 - Update book.json file\r\n\r\n1. In you gitbook's book.json file, add `intopic-toc` to plugins list.\r\n2. In pluginsConfig, configure the plugin so it does fit your needs. A custom setup is not mandatory.\r\n\r\n**Sample `book.json` file for gitbook version 2.0.0+**\r\n\r\n```json\r\n{\r\n  \"plugins\": [\r\n    \"intopic-toc\"\r\n  ]\r\n}\r\n```\r\n\r\n**Sample `book.json` file for gitbook version 2.0.0+ and custom heading**\r\n\r\n```json\r\n{\r\n  \"plugins\": [\r\n    \"intopic-toc\"\r\n  ],\r\n  \"pluginsConfig\": {\r\n    \"intopic-toc\": {\r\n      \"label\": \"In this article\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n**Sample `book.json` file for gitbook version 2.0.0+  and multilingual headings**\r\n\r\n```json\r\n{\r\n  \"plugins\": [\r\n    \"intopic-toc\"\r\n  ],\r\n  \"pluginsConfig\": {\r\n    \"intopic-toc\": {\r\n      \"label\": {\r\n        \"de\": \"In diesem Artikel\",\r\n        \"en\": \"In this article\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\nNote: Above snippets can be used as complete `book.json` file, if one of these matches your requirements and your book doesn't have one yet.\r\n\r\n### Step #2 - gitbook commands\r\n\r\n1. Run `gitbook install`. It will automatically install `intopic-toc` gitbook plugin for your book. This is needed only once.\r\n2. Build your book (`gitbook build`) or serve (`gitbook serve`) as usual.\r\n\r\n## Usage\r\n\r\nFor basic usage, the only thing you have to do is install the plugin. For advanced scenarios see following configuration sample.\r\n\r\n```json\r\n{\r\n  \"plugins\": [\r\n    \"intopic-toc\"\r\n  ],\r\n  \"pluginsConfig\": {\r\n    \"intopic-toc\": {\r\n      \"selector\": \".markdown-section h1, .markdown-section h2, .markdown-section h3, .markdown-section h4, .markdown-section h5, .markdown-section h6\",\r\n      \"mode\": \"nested\",\r\n      \"maxDepth\": 2,\r\n      \"isCollapsed\": false,\r\n      \"isScrollspyActive\": true,\r\n      \"visible\": true,\r\n      \"label\": {\r\n        \"de\": \"In diesem Artikel\",\r\n        \"en\": \"In this article\"\r\n      },\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n| Property | Description                                                  | Default value        |\r\n| -------- | ------------------------------------------------------------ | -------------------- |\r\n| selector | Selector used to find elements to put anchors on - only HTML headings h1 - h6 are allowed. | .markdown-section h1, .markdown-section h2, .markdown-section h3, .markdown-section h4, .markdown-section h5, .markdown-section h6 |\r\n| mode | Defines how plugin will be rendered. Possible values: 'flat' or 'nested'. | nested |\r\n| maxDepth | Defines the amount of headings which should be considered during rendering. | 6 |\r\n| isCollapsed | Defines whether the items are collapsed by default and are only expanded when activated. (Only considered when mode = 'nested') | true |\r\n| isScrollspyActive | Defines whether scrollspy effect should be applied. | true |\r\n| visible | Defines whether to show the navigation on every page | true |\r\n| label | Label which is used as heading for the navigation. Could be a single string or an object for multilingual setups | In this article |\r\n\r\n### Visibility\r\n\r\nIf `visible` parameter set to true and you want to hide the TOC on a single page, add the front matter item `isTocVisible: false` to the top of the Markdown file like this:\r\n\r\n```markdown\r\n---\r\nisTocVisible: false\r\n---\r\n# My awesome documentation\r\n\r\nLorem ipsum dolor sit amet, consetetur sadipscing elitr, ...\r\n```\r\n\r\nThe specific front matter `isTocVisible` overrides the `visible` parameter from global configuration.\r\n\r\n### Headings\r\n\r\nHeading are identified using `selector` property of the plugin. Usually there is no need to adjust the default value. For customizations see following sections.\r\n\r\nBy default, the plugin chooses the top-level navigation items by searching for headings at the first identified heading level using `selector` property value, then works its way down (`\u003ch1/\u003e`, then `\u003ch2/\u003e`, etc.) It will stop when it finds the first set of headings where more than one exists at that level. For example (assuming we do not have modified the `selector` property):\r\n\r\n```html\r\n\u003ch1\u003eTitle\u003c/h1\u003e\r\n...\r\n\u003ch2\u003e1 Section 1\u003c/h2\u003e\r\n\u003ch3\u003e1.1 Subsection\u003c/h3\u003e\r\n...\r\n\u003ch4\u003e1.1.1 Subsection\u003c/h4\u003e\r\n...\r\n\u003ch3\u003e1.2 Subsection\u003c/h3\u003e\r\n...\r\n\u003ch2\u003e2 Section 2\u003c/h2\u003e\r\n\u003ch3\u003e2.1 Subsection\u003c/h3\u003e\r\n...\r\n```\r\n\r\nThe plugin would see there’s only one `\u003ch1\u003e`, then that `\u003ch2\u003e` appears two times. Then it stops and identified level becomes the top-level navigation items in the table of contents. Following headings under those (the `\u003ch3\u003e`s and `\u003ch4\u003e`s in this case) would be the next levels in the navigation.\r\n\r\nDescribed mechanism applies to all `flat` and `nested` mode. Rendering depth could be limited by specifying `maxDepth` property value.\r\n\r\nResulting table of contents using mode = `flat` and `maxDepth` = 2 would look like:\r\n\r\n```text\r\n1 Section 1\r\n1.1 Subsection\r\n1.2 Subsection\r\n2 Section 2\r\n2.1 Subsection\r\n```\r\n\r\nResulting table of contents using mode = `nested` and `maxDepth` = 2 would look like:\r\n\r\n```text\r\n1 Section 1\r\n  1.1 Subsection\r\n  1.2 Subsection\r\n2 Section 2\r\n  2.1 Subsection\r\n```\r\n\r\n## Troubleshooting\r\n\r\nIf inline TOC does not look as expected, check if your `book.json` is valid according to this documentation.\r\n\r\n## Changelog\r\n\r\n08/20/2022\r\n- Updated development dependencies and moved to GitHub Actions\r\n- Updated [anchorjs](https://github.com/bryanbraun/anchorjs) dependency to version 4.3.1\r\n\r\n05/03/2020\r\n- Added support for different layout modes along with improved scrollspy experience\r\n\r\n01/07/2019\r\n- Used [gumshoe scrollspy script](https://github.com/cferdinandi/gumshoe) for a better experience\r\n\r\n01/05/2019\r\n- Initial Release\r\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffzankl%2Fgitbook-plugin-intopic-toc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffzankl%2Fgitbook-plugin-intopic-toc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffzankl%2Fgitbook-plugin-intopic-toc/lists"}