PHPackages                             bit-mx/statamic-toc - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. bit-mx/statamic-toc

ActiveStatamic-addon[Utility & Helpers](/categories/utility)

bit-mx/statamic-toc
===================

Reusable TOC extraction and anchor injection for Statamic Bard and Markdown fields.

1.1.1(1mo ago)012MITPHPPHP ^8.4

Since Mar 6Pushed 1mo agoCompare

[ Source](https://github.com/bit-mx/statamic-toc)[ Packagist](https://packagist.org/packages/bit-mx/statamic-toc)[ RSS](/packages/bit-mx-statamic-toc/feed)WikiDiscussions master Synced 3w ago

READMEChangelog (4)Dependencies (18)Versions (5)Used By (0)

Statamic TOC
============

[](#statamic-toc)

A reusable Table of Contents package for Statamic that extracts headings from **HTML**, **Markdown**, and **Bard** content, generates stable anchors, and optionally injects heading IDs into rendered HTML.

Requirements
------------

[](#requirements)

- PHP 8.3+
- Laravel 12
- Statamic 6

Installation
------------

[](#installation)

```
composer require bit-mx/statamic-toc
```

Publish Configuration
---------------------

[](#publish-configuration)

```
php artisan vendor:publish --tag=statamic-toc-config
```

This publishes `config/statamic-toc.php`.

Configuration
-------------

[](#configuration)

```
return [
    'min_level' => 1,
    'max_level' => 6,
    'preserve_existing_ids' => true,
    'default_source' => 'html',
    'default_tree' => true,

    'cache' => [
        'enabled' => false,
        'ttl' => 600,
        'store' => null,
        'prefix' => 'statamic_toc',
    ],
];
```

### Key Options

[](#key-options)

- `min_level`, `max_level`: Heading level range included in TOC.
- `preserve_existing_ids`: Keep existing heading IDs when injecting anchors.
- `cache.enabled`: Enable caching for tag output.
- `cache.ttl`: Cache lifetime in seconds.

Usage
-----

[](#usage)

### Blade Tag Compatibility (``)

[](#blade-tag-compatibility-stoc)

This package is compatible with Statamic Blade tag usage like:

```

    @isset($toc_id)
        {{ $toc_title }}

        @if($has_children)
            @foreach($children as $child)
                {{ $child['toc_title'] }}
            @endforeach
        @endif
    @endisset

```

Supported legacy params:

- `content`
- `field` (default: `article`)
- `depth` (default: `3`)
- `from` (default: `h1`)
- `is_flat` (default: `false`)

Legacy output keys are provided for drop-in compatibility:

- `toc_title`
- `toc_id`
- `toc_level`
- `children`
- `has_children`
- `total_children`
- `total_results`
- `no_results`

Tag Usage (Antlers / Blade context)
-----------------------------------

[](#tag-usage-antlers--blade-context)

Use the `toc` tag to extract TOC items.

```
{{ toc:items source="html" :content="content" min_level="2" max_level="4" }}
  {{ text }}
{{ /toc:items }}
```

Parameters:

- `source`: `html`, `markdown`, or `bard`.
- `content`: The input payload to parse.
- `min_level` / `max_level`: Optional level limits.
- `tree`: `true`/`false` to return hierarchical or flat output.

Modifier Usage
--------------

[](#modifier-usage)

Inject heading IDs into rendered HTML:

```
{{ content | toc }}
```

Optional params:

```
{{ content | toc:2:4:true }}
```

Meaning:

1. min level
2. max level
3. preserve existing IDs

Service / Facade Usage (PHP)
----------------------------

[](#service--facade-usage-php)

```
use BitMx\StatamicToc\Facades\Toc;

$items = Toc::extractAsArray('markdown', $markdown, 1, 6, true);
```

Or via DI:

```
use BitMx\StatamicToc\Toc\TocService;

public function show(TocService $tocService): array
{
    return $tocService->extractAsArray('html', $html, 2, 4, true);
}
```

Output Shape
------------

[](#output-shape)

Each item includes:

- `text`
- `level`
- `id`
- `url` (for example, `#installation`)
- `children` (when `tree=true`)

Bard Integration Notes
----------------------

[](#bard-integration-notes)

The Bard extractor walks nested node structures and set values, so headings inside nested/complex Bard content are included.

Caching
-------

[](#caching)

When `cache.enabled=true`, tag results are cached using a key that includes source, content, level range, and tree mode.

Migration from In-App TOC Logic
-------------------------------

[](#migration-from-in-app-toc-logic)

If you already have custom parser/tag/modifier classes in your project:

1. Install this package.
2. Replace custom TOC tag calls with package tag usage.
3. Replace custom heading-id injection with `| toc` modifier.
4. Keep your front-end template markup, only swap data source.
5. Remove legacy TOC classes after parity verification.

Troubleshooting
---------------

[](#troubleshooting)

### IDs are not added to headings

[](#ids-are-not-added-to-headings)

- Ensure content passed to modifier is rendered HTML.
- Confirm heading levels are within configured min/max.

### Duplicate anchors

[](#duplicate-anchors)

- Duplicate heading text is expected to produce suffixes (`-2`, `-3`, ...).

### Missing Bard headings

[](#missing-bard-headings)

- Verify the field content passed to source `bard` is raw Bard data (array structure).

### Cache not updating

[](#cache-not-updating)

- Disable cache during development.
- Check cache store and TTL settings.

Testing
-------

[](#testing)

```
composer test
```

License
-------

[](#license)

MIT

###  Health Score

42

—

FairBetter than 89% of packages

Maintenance90

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~20 days

Total

4

Last Release

49d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/37640480?v=4)[jenriquez](/maintainers/jenriquez)[@jenriquez](https://github.com/jenriquez)

---

Top Contributors

[![jenriquez-bit](https://avatars.githubusercontent.com/u/44071711?v=4)](https://github.com/jenriquez-bit "jenriquez-bit (6 commits)")

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/bit-mx-statamic-toc/health.svg)

```
[![Health](https://phpackages.com/badges/bit-mx-statamic-toc/health.svg)](https://phpackages.com/packages/bit-mx-statamic-toc)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3345.1M337](/packages/psalm-plugin-laravel)[illuminate/pipeline

The Illuminate Pipeline package.

9348.3M267](/packages/illuminate-pipeline)[illuminate/pagination

The Illuminate Pagination package.

10533.5M989](/packages/illuminate-pagination)[illuminate/redis

The Illuminate Redis package.

8314.4M362](/packages/illuminate-redis)[statamic/seo-pro

68488.6k](/packages/statamic-seo-pro)[illuminate/cookie

The Illuminate Cookie package.

224.5M132](/packages/illuminate-cookie)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)