{"id":13689533,"url":"https://github.com/jdsteinbach/eleventy-plugin-toc","last_synced_at":"2025-04-10T01:10:01.476Z","repository":{"id":42704679,"uuid":"137820209","full_name":"jdsteinbach/eleventy-plugin-toc","owner":"jdsteinbach","description":"11ty plugin to generate a TOC from page content","archived":false,"fork":false,"pushed_at":"2024-09-08T19:55:14.000Z","size":171,"stargazers_count":65,"open_issues_count":20,"forks_count":19,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-10T01:09:56.326Z","etag":null,"topics":["eleventy","eleventy-plugin","hacktoberfest","javascript"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jdsteinbach.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2018-06-19T00:19:59.000Z","updated_at":"2025-02-25T20:21:18.000Z","dependencies_parsed_at":"2024-01-14T17:42:14.233Z","dependency_job_id":"d6b37a32-b204-4203-9225-19ad31697c4e","html_url":"https://github.com/jdsteinbach/eleventy-plugin-toc","commit_stats":{"total_commits":38,"total_committers":2,"mean_commits":19.0,"dds":"0.21052631578947367","last_synced_commit":"c9f758ea89e2b887621d5678dfd104a0f23c838f"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdsteinbach%2Feleventy-plugin-toc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdsteinbach%2Feleventy-plugin-toc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdsteinbach%2Feleventy-plugin-toc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdsteinbach%2Feleventy-plugin-toc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jdsteinbach","download_url":"https://codeload.github.com/jdsteinbach/eleventy-plugin-toc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248137886,"owners_count":21053775,"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":["eleventy","eleventy-plugin","hacktoberfest","javascript"],"created_at":"2024-08-02T15:01:51.460Z","updated_at":"2025-04-10T01:10:01.451Z","avatar_url":"https://github.com/jdsteinbach.png","language":"JavaScript","funding_links":[],"categories":["javascript"],"sub_categories":[],"readme":"# eleventy-plugin-toc\n\nThis Eleventy plugin will generate a TOC from page content using an Eleventy filter.\n\n## Default Options\n\n```js\n{\n  tags: ['h2', 'h3', 'h4'], // which heading tags are selected headings must each have an ID attribute\n  wrapper: 'nav',           // element to put around the root `ol`/`ul`\n  wrapperClass: 'toc',      // class for the element around the root `ol`/`ul`\n  ul: false,                // if to use `ul` instead of `ol`\n  flat: false,              // if subheadings should appear as child of parent or as a sibling\n}\n```\n\n## Usage\n\n### 1. Install the plugin\n\n```sh\nnpm i --save eleventy-plugin-toc\n```\n\n### 2. Make sure your headings have anchor IDs\n\n**Your heading elements must have `id`s before this plugin will create a TOC.** If there aren't `id`s on your headings, there will be no anchors for this plugin to link to.\n\nI use [`markdown-it-anchor`](https://www.npmjs.com/package/markdown-it-anchor) to add those `id`s to the headings: [Eleventy config example](https://github.com/jdsteinbach/jdsteinbach.github.io/blob/blog/.eleventy.js)\n\n```js\n// .eleventy.js\n\nconst markdownIt = require('markdown-it')\nconst markdownItAnchor = require('markdown-it-anchor')\n\nmodule.exports = eleventyConfig =\u003e {\n  // Markdown\n  eleventyConfig.setLibrary(\n    'md',\n    markdownIt().use(markdownItAnchor)\n  )\n  // ... your other Eleventy config options\n}\n```\n\n### 3. Add this plugin to your Eleventy config\n\n```js\n// .eleventy.js\n\nconst pluginTOC = require('eleventy-plugin-toc')\n\nmodule.exports = function (eleventyConfig) {\n  eleventyConfig.addPlugin(pluginTOC)\n}\n```\n\n#### 3.1 You can override the default plugin options\n\n```js\nmodule.exports = function (eleventyConfig) {\n  eleventyConfig.addPlugin(pluginTOC, {\n    tags: ['h2', 'h3'],\n    wrapper: 'div'\n  })\n}\n```\n\n### 4. Use the filter in your layout template(s)\n\nBecause Eleventy only provides the `content` variable to layout templates (not to content files), you'll need to put this markup in a layout template:\n\n```liquid\n\u003carticle\u003e\n  {{ content }}\n\u003c/article\u003e\n\u003caside\u003e\n  {{ content | toc }}\n\u003c/aside\u003e\n```\n\nIf you're using Nunjucks, include the `safe` filter:\n\n```njk\n\u003carticle\u003e\n  {{ content | safe }}\n\u003c/article\u003e\n\u003caside\u003e\n  {{ content | toc | safe }}\n\u003c/aside\u003e\n```\n\nIf you want to conditionally render a wrapper element, the filter will return `undefined` when no markup is generated:\n\n\n```liquid\n{% if content | toc %}\n  \u003caside\u003e\n    {{ content | toc }}\n  \u003c/aside\u003e\n{% endif %}\n```\n\n### 5. Override default options if necessary\n\nPass a stringified JSON object (must be `JSON.parse()`-able) as an option for in your template. Because this is an object, you only need to include the key-value pairs you need to override; [defaults](#default-options) will be preserved.\n\n```liquid\n\u003caside\u003e\n  {{ content | toc: '{\"tags\":[\"h2\",\"h3\"],\"wrapper\":\"div\",\"wrapperClass\":\"content-tableau\"}' }}\n\u003c/aside\u003e\n```\n\n## Options\n\n| Name | Default Value | Type | Purpose |\n| --- | --- | --- | --- |\n| tags | `['h2', 'h3', 'h4']` | array of strings | which heading tags are used to generate the table of contents |\n| wrapper | `'nav'` | string | tag of element wrapping toc lists; `''` removes wrapper element |\n| wrapperClass | `'toc'` | string | `class` on element wrapping toc lists |\n| wrapperLabel | `undefined` | string | `aria-label` on element wrapping toc lists |\n| ul | `false` | boolean | lists are `ul` if true, `ol` if `false` |\n| flat | `false` | boolean | use flat list if `true`; use nested lists if false |\n\n## Roadmap\n\n- [ ] Some tests would be nice\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjdsteinbach%2Feleventy-plugin-toc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjdsteinbach%2Feleventy-plugin-toc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjdsteinbach%2Feleventy-plugin-toc/lists"}