{"id":13607158,"url":"https://github.com/toshimaru/jekyll-toc","last_synced_at":"2025-05-15T06:03:20.061Z","repository":{"id":25323942,"uuid":"28750927","full_name":"toshimaru/jekyll-toc","owner":"toshimaru","description":"Jekyll plugin which generates a table of contents.","archived":false,"fork":false,"pushed_at":"2024-08-26T01:36:00.000Z","size":221,"stargazers_count":354,"open_issues_count":37,"forks_count":52,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-05-13T19:16:17.695Z","etag":null,"topics":["gem","jekyll","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/toshimaru.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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},"funding":{"github":"toshimaru"}},"created_at":"2015-01-03T18:12:53.000Z","updated_at":"2025-05-09T18:28:15.000Z","dependencies_parsed_at":"2024-01-14T04:52:15.953Z","dependency_job_id":"b3635d04-b509-4be1-8e5f-1763a20acaca","html_url":"https://github.com/toshimaru/jekyll-toc","commit_stats":{"total_commits":241,"total_committers":14,"mean_commits":"17.214285714285715","dds":"0.16182572614107882","last_synced_commit":"f24235ee6350d49768662d2c43a09e2fca28e1ec"},"previous_names":[],"tags_count":49,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toshimaru%2Fjekyll-toc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toshimaru%2Fjekyll-toc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toshimaru%2Fjekyll-toc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toshimaru%2Fjekyll-toc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toshimaru","download_url":"https://codeload.github.com/toshimaru/jekyll-toc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254283336,"owners_count":22045140,"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":["gem","jekyll","ruby"],"created_at":"2024-08-01T19:01:16.057Z","updated_at":"2025-05-15T06:03:20.017Z","avatar_url":"https://github.com/toshimaru.png","language":"Ruby","readme":"# jekyll-toc\n\n![CI](https://github.com/toshimaru/jekyll-toc/workflows/CI/badge.svg)\n[![Gem Version](https://badge.fury.io/rb/jekyll-toc.svg)](https://badge.fury.io/rb/jekyll-toc)\n[![Code Climate](https://codeclimate.com/github/toshimaru/jekyll-toc/badges/gpa.svg)](https://codeclimate.com/github/toshimaru/jekyll-toc)\n[![Test Coverage](https://api.codeclimate.com/v1/badges/cd56b207f327603662a1/test_coverage)](https://codeclimate.com/github/toshimaru/jekyll-toc/test_coverage)\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Basic Usage](#basic-usage)\n  - [Advanced Usage](#advanced-usage)\n- [Generated HTML](#generated-html)\n- [Customization](#customization)\n  - [Default Configuration](#default-configuration)\n  - [TOC levels](#toc-levels)\n  - [Enable TOC by default](#enable-toc-by-default)\n  - [Skip TOC](#skip-toc)\n  - [Skip TOC Sectionally](#skip-toc-sectionally)\n  - [CSS Styling](#css-styling)\n  - [Custom CSS Class and ID](#custom-css-class-and-id)\n  - [Using Unordered/Ordered lists](#using-unorderedordered-lists)\n- [Alternative Tools](#alternative-tools)\n\n## Installation\n\nAdd jekyll-toc plugin in your site's `Gemfile`, and run `bundle install`.\n\n```ruby\ngem 'jekyll-toc'\n```\n\nAdd jekyll-toc to the `gems:` section in your site's `_config.yml`.\n\n```yml\nplugins:\n  - jekyll-toc\n```\n\nSet `toc: true` in posts for which you want the TOC to appear.\n\n```yml\n---\nlayout: post\ntitle: \"Welcome to Jekyll!\"\ntoc: true\n---\n```\n\n## Usage\n\nThere are three Liquid filters, which can be applied to HTML content,\ne.g. the Liquid variable `content` available in Jekyll's templates.\n\n### Basic Usage\n\n#### `toc` filter\n\nAdd the `toc` filter to your site's `{{ content }}` (e.g. `_layouts/post.html`).\n\n```liquid\n{{ content | toc }}\n```\n\nThis filter places the TOC directly above the content.\n\n### Advanced Usage\n\nIf you'd like separated TOC and content, you can use `{% toc %}` tag (or `toc_only` filter) and `inject_anchors` filter.\n\n#### `{% toc %}` tag / `toc_only` filter\n\nGenerates the TOC itself as described [below](#generated-html).\nMostly useful in cases where the TOC should _not_ be placed immediately\nabove the content but at some other place of the page, i.e. an aside.\n\n```html\n\u003cdiv\u003e\n  \u003cdiv id=\"table-of-contents\"\u003e\n    {% toc %}\n  \u003c/div\u003e\n  \u003cdiv id=\"markdown-content\"\u003e\n    {{ content }}\n  \u003c/div\u003e\n\u003c/div\u003e\n```\n\n:warning: **`{% toc %}` Tag Limitation**\n\n`{% toc %}` works only for [Jekyll Posts](https://jekyllrb.com/docs/step-by-step/08-blogging/) and [Jekyll Collections](https://jekyllrb.com/docs/collections/).\nIf you'd like to use `{% toc %}` except posts or collections, please use `toc_only` filter as described below.\n\n```html\n\u003cdiv\u003e\n  \u003cdiv id=\"table-of-contents\"\u003e\n    {{ content | toc_only }}\n  \u003c/div\u003e\n  \u003cdiv id=\"markdown-content\"\u003e\n    {{ content | inject_anchors }}\n  \u003c/div\u003e\n\u003c/div\u003e\n```\n\n#### `inject_anchors` filter\n\nInjects HTML anchors into the content without actually outputting the TOC itself.\nThey are of the form:\n\n```html\n\u003ca class=\"anchor\" href=\"#heading1-1\" aria-hidden=\"true\"\u003e\n  \u003cspan class=\"octicon octicon-link\"\u003e\u003c/span\u003e\n\u003c/a\u003e\n```\n\nThis is only useful when the TOC itself should be placed at some other\nlocation with the `toc_only` filter.\n\n## Generated HTML\n\njekyll-toc generates an unordered list by default. The HTML output is as follows.\n\n```html\n\u003cul id=\"toc\" class=\"section-nav\"\u003e\n  \u003cli class=\"toc-entry toc-h1\"\u003e\u003ca href=\"#heading1\"\u003eHeading.1\u003c/a\u003e\n    \u003cul\u003e\n      \u003cli class=\"toc-entry toc-h2\"\u003e\u003ca href=\"#heading1-1\"\u003eHeading.1-1\u003c/a\u003e\u003c/li\u003e\n      \u003cli class=\"toc-entry toc-h2\"\u003e\u003ca href=\"#heading1-2\"\u003eHeading.1-2\u003c/a\u003e\u003c/li\u003e\n    \u003c/ul\u003e\n  \u003c/li\u003e\n  \u003cli class=\"toc-entry toc-h1\"\u003e\u003ca href=\"#heading2\"\u003eHeading.2\u003c/a\u003e\n    \u003cul\u003e\n      \u003cli class=\"toc-entry toc-h2\"\u003e\u003ca href=\"#heading2-1\"\u003eHeading.2-1\u003c/a\u003e\n        \u003cul\u003e\n          \u003cli class=\"toc-entry toc-h3\"\u003e\u003ca href=\"#heading2-1-1\"\u003eHeading.2-1-1\u003c/a\u003e\u003c/li\u003e\n          \u003cli class=\"toc-entry toc-h3\"\u003e\u003ca href=\"#heading2-1-2\"\u003eHeading.2-1-2\u003c/a\u003e\u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/li\u003e\n      \u003cli class=\"toc-entry toc-h2\"\u003e\u003ca href=\"#heading2-2\"\u003eHeading.2-2\u003c/a\u003e\u003c/li\u003e\n    \u003c/ul\u003e\n  \u003c/li\u003e\n\u003c/ul\u003e\n```\n\n![screenshot](https://user-images.githubusercontent.com/803398/28401295-0dcfb7ca-6d54-11e7-892b-2f2e6ca755a7.png)\n\n## Customization\n\njekyll-toc is customizable on `_config.yml`.\n\n### Default Configuration\n\n```yml\n# _config.yml\ntoc:\n  min_level: 1\n  max_level: 6\n  ordered_list: false\n  no_toc_section_class: no_toc_section\n  list_id: toc\n  list_class: section-nav\n  sublist_class: ''\n  item_class: toc-entry\n  item_prefix: toc-\n```\n\n### TOC levels\n\n```yml\n# _config.yml\ntoc:\n  min_level: 2 # default: 1\n  max_level: 5 # default: 6\n```\n\nThe default heading range is from `\u003ch1\u003e` to `\u003ch6\u003e`.\n\n### Enable TOC by default\n\nYou can enable TOC by default with [Front Matter Defaults](https://jekyllrb.com/docs/configuration/front-matter-defaults/):\n\n```yml\n# _config.yml\ndefaults:\n  - scope:\n      path: \"\"\n    values:\n      toc: true\n```\n\n### Skip TOC\n\nThe heading is ignored in the toc by adding `no_toc` class.\n\n```html\n\u003ch1\u003eh1\u003c/h1\u003e\n\u003ch1 class=\"no_toc\"\u003eThis heading is ignored in the TOC\u003c/h1\u003e\n\u003ch2\u003eh2\u003c/h2\u003e\n```\n\n### Skip TOC Sectionally\n\nThe headings are ignored inside the element which has `no_toc_section` class.\n\n```html\n\u003ch1\u003eh1\u003c/h1\u003e\n\u003cdiv class=\"no_toc_section\"\u003e\n  \u003ch2\u003eThis heading is ignored in the TOC\u003c/h2\u003e\n  \u003ch3\u003eThis heading is ignored in the TOC\u003c/h3\u003e\n\u003c/div\u003e\n\u003ch4\u003eh4\u003c/h4\u003e\n```\n\nWhich would result in only the `\u003ch1\u003e` \u0026 `\u003ch4\u003e` within the example being included in the TOC.\n\nThe class can be configured on `_config.yml`:\n\n```yml\n# _config.yml\ntoc:\n  no_toc_section_class: exclude # default: no_toc_section\n```\n\nConfiguring multiple classes are allowed:\n\n```yml\n# _config.yml\ntoc:\n  no_toc_section_class:\n    - no_toc_section\n    - exclude\n    - your_custom_skip_class_name\n```\n\n### CSS Styling\n\nThe toc can be modified with CSS. The sample CSS is the following.\n\n```css\n.section-nav {\n  background-color: #fff;\n  margin: 5px 0;\n  padding: 10px 30px;\n  border: 1px solid #e8e8e8;\n  border-radius: 3px;\n}\n```\n\n![screenshot](https://user-images.githubusercontent.com/803398/28401455-0ba60868-6d55-11e7-8159-0ae7591aee66.png)\n\nEach TOC `li` entry has two CSS classes for further styling. The general `toc-entry` is applied to all `li` elements in the `ul.section-nav`.\n\nDepending on the heading level each specific entry refers to, it has a second CSS class `toc-XX`, where `XX` is the HTML heading tag name.\nFor example, the TOC entry linking to a heading `\u003ch1\u003e...\u003c/h1\u003e` (a single `#` in Markdown) will get the CSS class `toc-h1`.\n\n### Custom CSS Class and ID\n\nYou can apply custom CSS classes to the generated `\u003cul\u003e` and `\u003cli\u003e` tags.\n\n```yml\n# _config.yml\ntoc:\n  list_id: my-toc-id # Default: \"toc\"\n  list_class: my-list-class # Default: \"section-nav\"\n  sublist_class: my-sublist-class # Default: no class for sublists\n  item_class: my-item-class # Default: \"toc-entry\"\n  item_prefix: item- # Default: \"toc-\":\n```\n\n### Using Unordered/Ordered lists\n\nBy default the table of contents will be generated as an unordered list via `\u003cul\u003e\u003c/ul\u003e` tags. This can be configured to use ordered lists instead `\u003col\u003e\u003c/ol\u003e`.\nThis can be configured in `_config.yml`:\n\n```yml\n# _config.yml\ntoc:\n  ordered_list: true # default is false\n```\n\nIn order to change the list type, use the [list-style-type](https://developer.mozilla.org/en-US/docs/Web/CSS/list-style-type) css property.\nAdd a class to the `sublist_class` configuration to append it to the `ol` tags so that you can add the `list-style-type` property.\n\nExample\n\n```yml\n# _config.yml\ntoc:\n  ordered_list: true\n  list_class: my-list-class\n  sublist_class: my-sublist-class\n```\n\n```css\n.my-list-class {\n  list-style-type: upper-alpha;\n}\n\n.my-sublist-class: {\n  list-style-type: lower-alpha;\n}\n```\n\nThis will produce:\n\n![screenshot](https://user-images.githubusercontent.com/7675276/85813980-a0ea5a80-b719-11ea-9458-ccf9b86a778b.png)\n\n## Alternative Tools\n\n- Adding anchor to headings\n  - [AnchorJS](https://www.bryanbraun.com/anchorjs/)\n- Generating TOC for kramdown content\n  - [Automatic “Table of Contents” Generation](https://kramdown.gettalong.org/converter/html.html#toc) (See also. [Create Table of Contents in kramdown](https://blog.toshima.ru/2020/05/22/kramdown-toc))\n","funding_links":["https://github.com/sponsors/toshimaru"],"categories":["Text Filters","Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoshimaru%2Fjekyll-toc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoshimaru%2Fjekyll-toc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoshimaru%2Fjekyll-toc/lists"}