npm package: @smals-webagency/toc
Description: Automatic generation of a table of contents.
Author: Smals Webagency
Latest version: 3.0.0

# TOC
`smalsToc` is a script that generates a Table of Contents (TOC) based on the headings within a specified content element. It provides a simple way to create a navigation structure for your content.

## Getting started
Install with npm: `npm install @smals-webagency/toc`

## Include

### 1. `smalsToc` with jQuery

1. **Include jQuery**: ensure that jQuery is included in your project.

    ```html
    <script src="path/to/jquery.min.js"></script>
   <script src="path/to/smals-toc-jquery.js"></script>
    ```

2. **Call `smalsToc` on an element**: call the `smalsToc` method on an HTML element to generate the TOC.

    ```javascript
    $('#toc').smalsToc({
        // Options go here
    });
    ```

### 2. `smalsToc` without jQuery

1. **Include `smalsToc` script**: include the `smalsToc` script in your project.

    ```html
    <script src="path/to/smals-toc.js"></script>
    ```

2. **Call `smalsToc` on an element**: call the `smalsToc` method on an HTML element to generate the TOC.

    ```javascript
    document.getElementById('toc').smalsToc({
        // Options go here
    });
    ```

### 3. `smalsToc` bundle for webpack

**With jQuery**:

```javascript
// app.js
import smalsToc from './smals-toc-jquery-bundle';

$('#toc').smalsToc({
   // Options go here
});
```

**Without jQuery**:

```javascript
// app.js
import smalsToc from './smals-toc-bundle';

document.getElementById('toc').smalsToc({
   // Options go here
});
```

## Options

The `smalsToc` script supports the following options:

| Name               | Default value   | Description                                                                                                                      |
|:-------------------|:----------------|:---------------------------------------------------------------------------------------------------------------------------------|
| `contentElementId` | `'toc-content'` | Specifies the ID of the content element containing the headings.                                                                 |                                                                                    |
| `listTag`          | `'ul'`          | Specifies the HTML tag to be used for the list (e.g., 'ul' or 'ol').                                                             |
| `listClass`        | `''`            | Specifies the CSS class to be applied to the list.                                                                                                      |
| `listItemClass`    | `''`            | Specifies the CSS class to be applied to each list item.                                                                                               |
| `linkClass`        | `''`            | Specifies the CSS class to be applied to each anchor link.                                                                                                |
| `headings`         | `'h2, h3, h4'`  | Specifies the headings to be included in the Table of Contents. It should be a comma-separated string of HTML heading tags.                                                            |
| `ignoreClass`      | `'toc-ignore'`  | Specifies the CSS class that, when applied to a heading or its ancestors, excludes the heading from the Table of Contents.                                                      |
| `scrollSpy`        | `true`          | Enable or disable the scrollSpy functionality. When set to `true`, the TOC will automatically highlight the active section based on the user's scrolling.                                                      |

## Functionality

- The script creates a Table of Contents based on the headings within the specified content element.
- Each heading is transformed into an anchor link within the TOC.
- The script normalizes heading text to create unique anchor names.
- The TOC structure mirrors the heading structure, maintaining hierarchy.
- Optionally, the script supports custom CSS classes for styling.

## Example

```html
<body>
<div id="toc-content">
   <h2>Section 1</h2>
   <h3>Subsection 1.1</h3>
   <h3 class="toc-ignore">Subsection 1.2 (Ignored)</h3>
   <h2>Section 2</h2>
</div>

<div id="toc"></div>

<!-- Include jQuery -->
<script src="path/to/jquery.min.js"></script>

<!-- Include smalsToc script -->
<script src="path/to/smalsToc-jquery.js"></script>

<script>
   $('#toc').smalsToc({
      contentElementId: 'toc-content',
      listTag: 'ul',
      listClass: 'custom-list',
      listItemClass: 'custom-list-item',
      linkClass: 'custom-link',
      headings: 'h2, h3',
      ignoreClass: 'toc-ignore'
   });
</script>
</body>
```