中文

nuxt-toc

A Nuxt module for table of contents (TOC) component in your Nuxt Content projects.

• ✨  Release Notes

Features ✨

• 🎨 Highly Customizable: Tailor it to fit your unique needs.
• 🔍 Active TOC Highlighting: Easily see which section you're in.
• 📦 Out of the Box: Ready to use with minimal setup.
• 🔗 Section Links: Navigate seamlessly within your content.
• ♿ ARIA Support: Ensures accessibility for all users.
• 🆓 Free and Open Source (MIT License): Enjoy the freedom to use, modify, and distribute.

Quick Start 🔧

1. Install the module to your Nuxt application:

npx nuxi module add nuxt-toc

2. Add <TableOfContents /> at where you need the TOC.

<template>
    <ContentDoc />
    <TableOfContents />
</template>

You can also pass in TOC yourself to prevent duplicate fetching.

<template>
    <ContentRenderer :value="data" />
    <TableOfContents :toc="data.body.toc" />
</template>

<script setup>
const route = useRoute()

const { data } = await useAsyncData('home', () => queryContent(route.path).findOne())
</script>

Props

| Prop | Type | Default | Description | |--------------------|----------|-------------|-----------------------------------------------------------------------------------------------------| | toc | JSON | null | Use the provided toc data. If toc is passed in, this component will not fetch TOC info itself and path prop will be ignored.| | path | String | '' | The path to the content for which the TOC is generated. Defaults to using the current URI if not set. | | isSublistShown | Boolean | true | Determines whether the sublist within the TOC is shown. | | isTitleShownWithNoContent | Boolean | false | Determines whether the title is shown even if there is no content in the TOC. | | title | String | 'Table of Contents' | The title of the TOC. |

Styling

| ID/Class | Type | Description | |-----------------------------|----------|-----------------------------------------------------------------------------------------------------| | toc-container | ID | The container for the table of contents (TOC). | | toc-title | ID | The title of the table of contents. | | toc-item | Class | General class for TOC items. | | toc-topitem | Class | Specific class for top-level TOC items. | | active-toc-item | Class | Applied to active TOC items. | | active-toc-topitem | Class | Applied to active top-level TOC items. | | toc-link | Class | General class for TOC links. | | toc-toplink | Class | Specific class for top-level TOC links. | | toc-sublist | Class | Styles the sublist within the TOC. | | toc-subitem | Class | Specific class for sub-level TOC items. | | active-toc-subitem | Class | Applied to active sub-level TOC items. | | toc-sublink | Class | Specific class for sub-level TOC links. | | toc-item-${link.id} | ID | Dynamically generated ID for each TOC item, based on the link.id. | | toc-topitem-and-sublist | Class | Styles the top-level TOC items and their sublists. |

[!NOTE] The default styling of the <TableOfContents /> component is:

.active-toc-item {
  color: #fef08a;
}

.toc-sublist-item {
  padding-left: 1rem;
}

a {
  text-decoration: none;
  color: inherit;
}

ul,
ol {
  list-style: none;
  padding: 0;
  margin: 0;
}

You can customize the style or reset it with:

.active-toc-item {
  color: initial;
}

.toc-sublist-item {
  padding-left: initial;
}

a {
  text-decoration: underline;
  color: initial;
}

ul,
ol {
  list-style: initial;
  padding: initial;
  margin: initial;
}

Cookbook

Example One

Custom color for active items and custom padding for subitems

<template>
    <ContentDoc />
    <TableOfContents />
</template>

<style>
/* Styling for active Table of Contents items */
.active-toc-item {
  color: #4ade80;
}

/* Indentation for second-level Table of Contents items */
.toc-sublist-item {
  padding-left: 1.5rem;
}
</style>

<!-- Or with Tailwind CSS
<style>
.active-toc-item {
  @apply text-green-300
}

.toc-sublist-item {
  @apply pl-1.5
}
</style>
-->

Result:

Example Two

Having a bar at left of each item

<template>
    <ContentDoc />
    <TableOfContents />
</template>

<style>
.toc-item {
  border-left-width: 2px;
  border-left-style: solid;
  border-color: #e5e7eb;
  padding-left: 0.25rem /* 4px */;
}

.active-toc-item {
  color: #60a5fa;
  border-color: #60a5fa;
}

.toc-sublist-item {
  padding-left: 1rem;
}
</style>

<!-- Or with Tailwind CSS
<style>
.toc-item {
  @apply border-l-2 pl-1
}

.active-toc-item {
  @apply text-blue-400 border-blue-400
}

.toc-sublist-item {
  @apply pl-4
}
</style>
-->

Result:

Example Three

First level titles be active when any of it's second level titles be active.

<template>
    <ContentDoc />
    <TableOfContents />
</template>

<style>
/* Sublist item is contained in sub list, which is top item's sibling */
.active-toc-item, .toc-topitem:has(+ .toc-sublist .active-toc-sublist-item) {
  color: #60a5fa
}

.active-toc-sublist-item {
  color: #4ade80
}

.toc-sublist-item {
  padding-left: 1rem /* 16px */;
}
</style>

<!-- Or with Tailwind CSS
<style>
.active-toc-item, .toc-topitem:has(+ .toc-sublist .active-toc-sublist-item) {
  @apply text-blue-400
}

.active-toc-sublist-item {
  @apply text-green-400
}

.toc-sublist-item {
  @apply pl-4
}
</style>
-->

Result:

License

This project is under MIT license.