Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork53
Jekyll plugin which generates a table of contents.
License
toshimaru/jekyll-toc
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Add jekyll-toc plugin in your site'sGemfile, and runbundle install.
gem'jekyll-toc'
Add jekyll-toc to thegems: section in your site's_config.yml.
plugins: -jekyll-toc
Settoc: true in posts for which you want the TOC to appear.
---layout:posttitle:"Welcome to Jekyll!"toc:true---
There are three Liquid filters, which can be applied to HTML content,e.g. the Liquid variablecontent available in Jekyll's templates.
Add thetoc filter to your site's{{ content }} (e.g._layouts/post.html).
{{content |toc }}This filter places the TOC directly above the content.
If you'd like separated TOC and content, you can use{% toc %} tag (ortoc_only filter) andinject_anchors filter.
Generates the TOC itself as describedbelow.Mostly useful in cases where the TOC shouldnot be placed immediatelyabove the content but at some other place of the page, i.e. an aside.
<div><divid="table-of-contents"> {% toc %}</div><divid="markdown-content"> {{ content }}</div></div>
{% toc %} Tag Limitation
{% toc %} works only forJekyll Posts andJekyll Collections.If you'd like to use{% toc %} except posts or collections, please usetoc_only filter as described below.
<div><divid="table-of-contents"> {{ content | toc_only }}</div><divid="markdown-content"> {{ content | inject_anchors }}</div></div>
Injects HTML anchors into the content without actually outputting the TOC itself.They are of the form:
<aclass="anchor"href="#heading1-1"aria-hidden="true"><spanclass="octicon octicon-link"></span></a>
This is only useful when the TOC itself should be placed at some otherlocation with thetoc_only filter.
jekyll-toc generates an unordered list by default. The HTML output is as follows.
<ulid="toc"class="section-nav"><liclass="toc-entry toc-h1"><ahref="#heading1">Heading.1</a><ul><liclass="toc-entry toc-h2"><ahref="#heading1-1">Heading.1-1</a></li><liclass="toc-entry toc-h2"><ahref="#heading1-2">Heading.1-2</a></li></ul></li><liclass="toc-entry toc-h1"><ahref="#heading2">Heading.2</a><ul><liclass="toc-entry toc-h2"><ahref="#heading2-1">Heading.2-1</a><ul><liclass="toc-entry toc-h3"><ahref="#heading2-1-1">Heading.2-1-1</a></li><liclass="toc-entry toc-h3"><ahref="#heading2-1-2">Heading.2-1-2</a></li></ul></li><liclass="toc-entry toc-h2"><ahref="#heading2-2">Heading.2-2</a></li></ul></li></ul>
jekyll-toc is customizable on_config.yml.
# _config.ymltoc:min_level:1max_level:6ordered_list:falseno_toc_section_class:no_toc_sectionlist_id:toclist_class:section-navsublist_class:''item_class:toc-entryitem_prefix:toc-
# _config.ymltoc:min_level:2# default: 1max_level:5# default: 6
The default heading range is from<h1> to<h6>.
You can enable TOC by default withFront Matter Defaults:
# _config.ymldefaults: -scope:path:""values:toc:true
The heading is ignored in the toc by addingno_toc class.
<h1>h1</h1><h1class="no_toc">This heading is ignored in the TOC</h1><h2>h2</h2>
The headings are ignored inside the element which hasno_toc_section class.
<h1>h1</h1><divclass="no_toc_section"><h2>This heading is ignored in the TOC</h2><h3>This heading is ignored in the TOC</h3></div><h4>h4</h4>
Which would result in only the<h1> &<h4> within the example being included in the TOC.
The class can be configured on_config.yml:
# _config.ymltoc:no_toc_section_class:exclude# default: no_toc_section
Configuring multiple classes are allowed:
# _config.ymltoc:no_toc_section_class: -no_toc_section -exclude -your_custom_skip_class_name
The toc can be modified with CSS. The sample CSS is the following.
.section-nav {background-color:#fff;margin:5px0;padding:10px30px;border:1px solid#e8e8e8;border-radius:3px;}
Each TOCli entry has two CSS classes for further styling. The generaltoc-entry is applied to allli elements in theul.section-nav.
Depending on the heading level each specific entry refers to, it has a second CSS classtoc-XX, whereXX is the HTML heading tag name.For example, the TOC entry linking to a heading<h1>...</h1> (a single# in Markdown) will get the CSS classtoc-h1.
You can apply custom CSS classes to the generated<ul> and<li> tags.
# _config.ymltoc:list_id:my-toc-id# Default: "toc"list_class:my-list-class# Default: "section-nav"sublist_class:my-sublist-class# Default: no class for sublistsitem_class:my-item-class# Default: "toc-entry"item_prefix:item-# Default: "toc-":
By default the table of contents will be generated as an unordered list via<ul></ul> tags. This can be configured to use ordered lists instead<ol></ol>.This can be configured in_config.yml:
# _config.ymltoc:ordered_list:true# default is false
In order to change the list type, use thelist-style-type css property.Add a class to thesublist_class configuration to append it to theol tags so that you can add thelist-style-type property.
Example
# _config.ymltoc:ordered_list:truelist_class:my-list-classsublist_class:my-sublist-class
.my-list-class {list-style-type: upper-alpha;}.my-sublist-class: {list-style-type: lower-alpha;}
This will produce:
- Adding anchor to headings
- Generating TOC for kramdown content
About
Jekyll plugin which generates a table of contents.
Topics
Resources
License
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Sponsor this project
Uh oh!
There was an error while loading.Please reload this page.
Packages0
Contributors14
Uh oh!
There was an error while loading.Please reload this page.