Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/hanyujie2002/nuxt-toc
A nuxt.js module for Table of Contents (TOC)
https://github.com/hanyujie2002/nuxt-toc
nuxt table-of-contents toc
Last synced: 6 days ago
JSON representation
A nuxt.js module for Table of Contents (TOC)
- Host: GitHub
- URL: https://github.com/hanyujie2002/nuxt-toc
- Owner: hanyujie2002
- License: mit
- Created: 2024-08-21T07:05:00.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2024-10-18T13:44:00.000Z (20 days ago)
- Last Synced: 2024-10-18T15:53:51.452Z (20 days ago)
- Topics: nuxt, table-of-contents, toc
- Language: Vue
- Homepage:
- Size: 1.96 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[中文](./README_zh.md)
# nuxt-toc
[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![License][license-src]][license-href]
[![Nuxt][nuxt-src]][nuxt-href]
A Nuxt module for table of contents (TOC) component in your Nuxt Content projects.
- [✨ Release Notes](https://github.com/hanyujie2002/nuxt-toc/releases)
## 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:
```bash
npx nuxi module add nuxt-toc
```
2. Add `` at where you need the TOC.
```vue
```
You can also pass in TOC yourself to prevent duplicate fetching.
```vue
const route = useRoute()
const { data } = await useAsyncData('home', () => queryContent(route.path).findOne())
```
## 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 `` component is:
>
> ```css
> .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:
>
> ```css
> .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
```vue
/* 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;
}
```
Result:
### Example Two
Having a bar at left of each item
```vue
.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;
}
```
Result:
### Example Three
First level titles be active when any of it's second level titles be active.
```vue
/* 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 */;
}
```
Result:
## License
This project is under [MIT](https://raw.githubusercontent.com/hanyujie2002/nuxt-toc/refs/heads/main/LICENSE) license.
[npm-version-src]: https://img.shields.io/npm/v/nuxt-toc/latest.svg?style=flat&colorA=020420&colorB=00DC82
[npm-version-href]: https://npmjs.com/package/nuxt-toc
[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-toc.svg?style=flat&colorA=020420&colorB=00DC82
[npm-downloads-href]: https://npmjs.com/package/nuxt-toc
[license-src]: https://img.shields.io/npm/l/nuxt-toc.svg?style=flat&colorA=020420&colorB=00DC82
[license-href]: https://npmjs.com/package/nuxt-toc
[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js
[nuxt-href]: https://nuxt.com