百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
J

jekyll-toc

> 编程语言
开源

一个 Jekyll 插件,用于生成目录表。

374 stars0 点赞4 次浏览
访问官网GitHub

工具介绍

一个 Jekyll 插件,用于生成目录表。

jekyll-toc

Table of Contents

  • Installation
  • Usage
    • Basic Usage
    • Advanced Usage
  • Generated HTML
  • Customization
    • Default Configuration
    • TOC levels
    • Enable TOC by default
    • Skip TOC
    • Skip TOC Sectionally
    • CSS Styling
    • Custom CSS Class and ID
    • Using Unordered/Ordered lists
  • Alternative Tools

Installation

Add jekyll-toc plugin in your site's Gemfile, and run bundle install.

ruby
gem 'jekyll-toc'

Add jekyll-toc to the gems: section in your site's _config.yml.

yaml
plugins:
  - jekyll-toc

Set toc: true in posts for which you want the TOC to appear.

yaml
---
layout: post
title: "Welcome to Jekyll!"
toc: true
---

Usage

There are three Liquid filters, which can be applied to HTML content, e.g. the Liquid variable content available in Jekyll's templates.

Basic Usage

toc filter

Add the toc filter to your site's {{ content }} (e.g. _layouts/post.html).

liquid
{{ content | toc }}

This filter places the TOC directly above the content.

Advanced Usage

If you'd like separated TOC and content, you can use {% toc %} tag (or toc_only filter) and inject_anchors filter.

{% toc %} tag / toc_only filter

Generates the TOC itself as described below. Mostly useful in cases where the TOC should not be placed immediately above the content but at some other place of the page, i.e. an aside.

xml

  

:warning: {% toc %} Tag Limitation

{% toc %} works only for Jekyll Posts and Jekyll Collections. If you'd like to use {% toc %} except posts or collections, please use toc_only filter as described below.

xml

  

inject_anchors filter

Injects HTML anchors into the content without actually outputting the TOC itself. They are of the form:

xml

  

This is only useful when the TOC itself should be placed at some other location with the toc_only filter.

Generated HTML

jekyll-toc generates an unordered list by default. The HTML output is as follows.

xml

  
Heading.1
    

      
Heading.1-1

      
Heading.1-2

    

  

  
Heading.2
    

      
Heading.2-1
        

          
Heading.2-1-1

          
Heading.2-1-2

        

      

      
Heading.2-2

    

  

Customization

jekyll-toc is customizable on _config.yml.

Default Configuration

yaml
# _config.yml
toc:
  min_level: 1
  max_level: 6
  ordered_list: false
  no_toc_section_class: no_toc_section
  list_id: toc
  list_class: section-nav
  sublist_class: ''
  item_class: toc-entry
  item_prefix: toc-

TOC levels

yaml
# _config.yml
toc:
  min_level: 2 # default: 1
  max_level: 5 # default: 6

The default heading range is from to .

Enable TOC by default

You can enable TOC by default with Front Matter Defaults:

yaml
# _config.yml
defaults:
  - scope:
      path: ""
    values:
      toc: true

Skip TOC

The heading is ignored in the toc by adding no_toc class.

xml

h1

This heading is ignored in the TOC

h2

Skip TOC Sectionally

The headings are ignored inside the element which has no_toc_section class.

xml

h1

h4

Which would result in only the & within the example being included in the TOC.

The class can be configured on _config.yml:

yaml
# _config.yml
toc:
  no_toc_section_class: exclude # default: no_toc_section

Configuring multiple classes are allowed:

yaml
# _config.yml
toc:
  no_toc_section_class:
    - no_toc_section
    - exclude
    - your_custom_skip_class_name

CSS Styling

The toc can be modified with CSS. The sample CSS is the following.

css
.section-nav {
  background-color: #fff;
  margin: 5px 0;
  padding: 10px 30px;
  border: 1px solid #e8e8e8;
  border-radius: 3px;
}

Each 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.

Depending 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. For example, the TOC entry linking to a heading ... (a single # in Markdown) will get the CSS class toc-h1.

Custom CSS Class and ID

You can apply custom CSS classes to the generated and tags.

yaml
# _config.yml
toc:
  list_id: my-toc-id # Default: "toc"
  list_class: my-list-class # Default: "section-nav"
  sublist_class: my-sublist-class # Default: no class for sublists
  item_class: my-item-class # Default: "toc-entry"
  item_prefix: item- # Default: "toc-":

Using Unordered/Ordered lists

By default the table of contents will be generated as an unordered list via `

tags. This can be configured to use ordered lists instead

. This can be configured in _config.yml`:

yaml
# _config.yml
toc:
  ordered_list: true # default is false

In order to change the list type, use the list-style-type css property. Add a class to the sublist_class configuration to append it to the ol tags so that you can add the list-style-type property.

Example

yaml
# _config.yml
toc:
  ordered_list: true
  list_class: my-list-class
  sublist_class: my-sublist-class
css
.my-list-class {
  list-style-type: upper-alpha;
}

.my-sublist-class: {
  list-style-type: lower-alpha;
}

This will produce:

Alternative Tools

  • Adding anchor to headings
    • AnchorJS
  • Generating TOC for kramdown content
    • Automatic “Table of Contents” Generation (See also. Create Table of Contents in kramdown)

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Rubygemjekyllruby

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言