{"id":24983641,"url":"https://github.com/posthtml/posthtml-toc","last_synced_at":"2026-03-16T17:36:42.960Z","repository":{"id":42827249,"uuid":"266310531","full_name":"posthtml/posthtml-toc","owner":"posthtml","description":"πTable of contents","archived":false,"fork":false,"pushed_at":"2023-03-04T19:59:24.000Z","size":805,"stargazers_count":4,"open_issues_count":5,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-29T21:06:08.269Z","etag":null,"topics":[],"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/posthtml.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":"contributing.md","funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2020-05-23T10:10:08.000Z","updated_at":"2021-09-24T05:17:38.000Z","dependencies_parsed_at":"2023-02-05T13:46:45.135Z","dependency_job_id":null,"html_url":"https://github.com/posthtml/posthtml-toc","commit_stats":{"total_commits":22,"total_committers":4,"mean_commits":5.5,"dds":0.5454545454545454,"last_synced_commit":"0c19ee4de97c5985fda86550d0590e29074191d4"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":"posthtml/posthtml-plugin-boilerplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posthtml%2Fposthtml-toc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posthtml%2Fposthtml-toc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posthtml%2Fposthtml-toc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posthtml%2Fposthtml-toc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/posthtml","download_url":"https://codeload.github.com/posthtml/posthtml-toc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248480512,"owners_count":21110936,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2025-02-04T09:19:58.705Z","updated_at":"2026-03-16T17:36:42.910Z","avatar_url":"https://github.com/posthtml.png","language":"JavaScript","readme":"# PostHTML TOC \u003cimg align=\"right\" width=\"220\" height=\"200\" title=\"PostHTML logo\" src=\"http://posthtml.github.io/posthtml/logo.svg\"\u003e\n\n[![NPM][npm]][npm-url]\n[![Standard Code Style][style]][style-url]\n\n\u003e A table of contents, usually headed simply Contents and abbreviated informally as TOC, is a list, usually found on a page before the start of a written work, of its chapter or section titles or brief descriptions with their commencing page numbers. [Wikipedia](https://en.wikipedia.org/wiki/Table_of_contents)\n\nThe plugin works particularly well with markdown documents.\n\nBy defaults \n\nBefore:\n``` html\n\u003chtml\u003e\n \u003cbody\u003e\n \u003ch1 id=\"title1\"\u003eTitle 1\u003c/h1\u003e\n \u003cp\u003ep1\u003c/p\u003e\n \u003ch2 id=\"title2\"\u003eTitle 2\u003c/h2\u003e\n \u003cp\u003ep2\u003c/p\u003e\n \u003ch3 id=\"title3\"\u003eTitle 3\u003c/h3\u003e\n \u003cp\u003ep3\u003c/p\u003e\n \u003c/body\u003e\n\u003c/html\u003e\n```\n\nAfter:\n``` html\n\u003chtml\u003e\n \u003cbody\u003e\n \u003ch1 id=\"title1\"\u003eTitle 1\u003c/h1\u003e\n \u003cdiv id=\"toc\"\u003e\n \u003cdiv id=\"toctitle\"\u003eContents\u003c/div\u003e\n \u003cul\u003e\n \u003cli\u003e\n \u003ca href=\"#title2\"\u003eTitle 2\u003c/a\u003e\n \u003cul\u003e\n \u003cli\u003e\u003ca href=\"#title3\"\u003eTitle 3\u003c/a\u003e\u003c/li\u003e\n \u003c/ul\u003e\n \u003c/li\u003e\n \u003c/ul\u003e\n \u003c/div\u003e\n \u003cp\u003ep1\u003c/p\u003e\n \u003ch2 id=\"title2\"\u003eTitle 2\u003c/h2\u003e\n \u003cp\u003ep2\u003c/p\u003e\n \u003ch3 id=\"title3\"\u003eTitle 3\u003c/h3\u003e\n \u003cp\u003ep3\u003c/p\u003e\n \u003c/body\u003e\n\u003c/html\u003e\n```\n\n## Install\n\nInstallation in your project\n\n```npm i posthtml posthtml-toc```\n\n## Usage\n\n``` js\nconst fs = require('fs');\nconst posthtml = require('posthtml');\nconst toc = require('posthtml-toc');\n\nposthtml()\n .use(toc({ /* options */ }))\n .process(html/*, options */)\n .then(result =\u003e fs.writeFileSync('./after.html', result.html));\n```\n\n## Options\n\nDefaults options\n\n* `insert = { after: 'h1' }` β insert the TOC immediately after the first `\u003ch1\u003e`\n* `title = \"Content\"` β Title TOC block\n* `ignoreMissingSelector = false` β throw an error if the selector is not found\n* `ignoreMissingHeadings = false` β throw an error if the no headings are found\n* `toggle` is undefined\n\n### `insert` option\n\nThis option allows you to specify where the TOC will be inserted in the HTML\noutput. The option expects an object with **exactly one key** with a string\nvalue, as in this schema:\n\n```\n{ insert: { \u003cposition\u003e: \u003cselector\u003e } }\n```\n\n`\u003cselector\u003e` is a string used to select an HTML element by matching one of three\npatterns:\n\n* `'\u003ctag\u003e'` β matches the first element with the name `\u003ctag\u003e`.\n\n _Example_: `'nav'` matches `\u003cnav\u003e`.\n\n* `'#\u003cid\u003e'` β matches the first element with `\u003cid\u003e` as the `id` attribute value.\n\n _Example_: `'#here'` matches `\u003cdiv id=\"here\"\u003e`.\n\n* `'.\u003cclass\u003e'` β matches the first element with `\u003cclass\u003e` as one of the\n space-separated strings in the `class` attribute value.\n\n _Example_: `'.here'` matches `\u003cdiv class=\"are you here or there\"\u003e`.\n\n`\u003cposition\u003e` can be one of the following:\n\n* `after` β The TOC will be inserted immediately after the matching node.\n\n _Example_: `{ insert: { after: 'h1' } }` (_default_) produces:\n\n ```diff\n \u003ch1\u003e...\u003c/h1\u003e\n +\u003cdiv id=\"toc\"\u003e...\u003c/div\u003e\n \u003cp\u003e...\u003c/p\u003e\n ```\n\n* `before` β The TOC will be inserted immediately before the matching node.\n\n _Example_: `{ insert: { before: '#here' } }` produces:\n\n ```diff\n \u003cp\u003e...\u003c/p\u003e\n +\u003cdiv id=\"toc\"\u003e...\u003c/div\u003e\n \u003cdiv id=\"here\"\u003e...\u003c/div\u003e\n ```\n\n* `afterChildren` β The TOC will be inserted into the contents of the matching\n node after the last child.\n\n _Example_: `{ insert: { afterChildren: '.here' } }` produces:\n\n ```diff\n \u003cnav class=\"here\"\u003e\n \u003cp\u003e...\u003c/p\u003e\n + \u003cdiv id=\"toc\"\u003e...\u003c/div\u003e\n \u003c/nav\u003e\n ```\n\n* `beforeChildren` β The TOC will be inserted into the contents of the matching\n node before the first child.\n\n _Example_: `{ insert: { beforeChildren: '.here' } }` produces:\n\n ```diff\n \u003cnav class=\"here\"\u003e\n + \u003cdiv id=\"toc\"\u003e...\u003c/div\u003e\n \u003cp\u003e...\u003c/p\u003e\n \u003c/nav\u003e\n ```\n\n### `toggle` options\nBefore:\n``` html\n\u003chtml\u003e\n \u003cbody\u003e\n \u003ch1 id=\"title1\"\u003eTitle 1\u003c/h1\u003e\n \u003cp\u003ep1\u003c/p\u003e\n \u003ch2 id=\"title2\"\u003eTitle 2\u003c/h2\u003e\n \u003cp\u003ep2\u003c/p\u003e\n \u003ch3 id=\"title3\"\u003eTitle 3\u003c/h3\u003e\n \u003cp\u003ep3\u003c/p\u003e\n \u003c/body\u003e\n\u003c/html\u003e\n```\nAdd option:\n``` js\nconst fs = require('fs');\nconst posthtml = require('posthtml');\nconst toc = require('posthtml-toc');\n\nposthtml()\n .use(toc({\n toggle: ['show', 'hide', true]\n }))\n .process(html/*, options */)\n .then(result =\u003e fs.writeFileSync('./after.html', result.html));\n```\nAfter:\n``` html\n\u003chtml\u003e\n \u003cbody\u003e\n \u003ch1 id=\"title1\"\u003eTitle 1\u003c/h1\u003e\n \u003cstyle\u003e\n #toctoggle,#toctoggle:checked~ul{display:none}\n #toctoggle~label:after{content:\"hide\"}\n #toctoggle:checked~label:after{content:\"show\"}\n #toc label{cursor:pointer}\n \u003c/style\u003e\n \u003cdiv id=\"toc\"\u003e\n \u003cinput type=\"checkbox\" role=\"button\" id=\"toctoggle\" checked\u003e\n \u003ch2\u003eContent\u003c/h2\u003e\n \u003clabel for=\"toctoggle\"\u003e\u003c/label\u003e\n \u003cul\u003e\n \u003cli\u003e\n \u003ca href=\"#title2\"\u003eTitle 2\u003c/a\u003e\n \u003cul\u003e\n \u003cli\u003e\u003ca href=\"#title3\"\u003eTitle 3\u003c/a\u003e\u003c/li\u003e\n \u003c/ul\u003e \n \u003c/li\u003e\n \u003c/ul\u003e\n \u003c/div\u003e\n \u003cp\u003ep1\u003c/p\u003e\n \u003ch2 id=\"title2\"\u003eTitle 2\u003c/h2\u003e\n \u003cp\u003ep2\u003c/p\u003e\n \u003ch3 id=\"title3\"\u003eTitle 3\u003c/h3\u003e\n \u003cp\u003ep3\u003c/p\u003e\n \u003c/body\u003e\n\u003c/html\u003e\n```\n\n### `ignoreMissingSelector` option\n\n* `{ ignoreMissingSelector: false }` (_default_) β throw an error if the\n selector (the default `h1` tag or the value passed to `options.after`) is not\n found.\n\n For example, with this option, you get an error on the second file because\n there is no `h1` tag:\n\n ```html\n \u003c!-- file-with-toc.html --\u003e\n \u003ch1\u003eTitle 1\u003c/h1\u003e\n \u003ch2 id=\"title2\"\u003eTitle 2\u003c/h2\u003e\n ```\n\n ```html\n \u003c!-- file-without-toc.html --\u003e\n \u003cdiv\u003e\u003c/div\u003e\n ```\n\n* `{ ignoreMissingSelector: true }` β ignore HTML input that does not have\n the selector.\n\n This is useful if you want to uniformly process a number of files but don't\n want to insert a TOC in all of them.\n\n For example, with the files mentioned above, instead of an error, the first\n file is modified and the second file is unchanged:\n\n ```html\n \u003c!-- file-with-toc.html --\u003e\n \u003ch1\u003eTitle 1\u003c/h1\u003e\n \u003cdiv id=\"toc\"\u003e\u003ch2\u003eContent\u003c/h2\u003e\u003cul\u003e\u003cli\u003e\u003ca href=\"#title2\"\u003eTitle 2\u003c/a\u003e\u003c/li\u003e\u003c/ul\u003e\u003c/div\u003e\n \u003ch2 id=\"title2\"\u003eTitle 2\u003c/h2\u003e\n ```\n\n ```html\n \u003c!-- file-without-toc.html --\u003e\n \u003cdiv\u003e\u003c/div\u003e\n ```\n\n### `ignoreMissingHeadings` option\n\nThis option controls what happens when no headings (`h2`, `h3`, `h4`, `h5`,\n`h6`) are found in the HTML input.\n\n* `{ ignoreMissingHeadings: false }` (_default_) β throw an error if no headings\n are found.\n\n* `{ ignoreMissingHeadings: true }` β do not throw an error if no headings are\n found. Instead, a TOC with an empty list (i.e. `\u003cul\u003e\u003c/ul\u003e`) will be inserted.\n\n### Contributing\n\nSee [PostHTML Guidelines](https://github.com/posthtml/posthtml/tree/master/docs) and [contribution guide](contributing.md).\n\n### License [MIT](license)\n\n[npm]: https://img.shields.io/npm/v/posthtml-toc.svg\n[npm-url]: https://npmjs.com/package/posthtml-toc\n\n[style]: https://img.shields.io/badge/code%20style-standard-yellow.svg\n[style-url]: http://standardjs.com/\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fposthtml%2Fposthtml-toc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fposthtml%2Fposthtml-toc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fposthtml%2Fposthtml-toc/lists"}