PHPackages                             jifish/parsedown-toc-ext - 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. [Parsing & Serialization](/categories/parsing)
4. /
5. jifish/parsedown-toc-ext

ActiveLibrary[Parsing & Serialization](/categories/parsing)

jifish/parsedown-toc-ext
========================

TOC extension for parsedown and parsedown-extra with automatic heading IDs.

1.0.0(3mo ago)02MITPHPPHP ^8.1

Since Mar 7Pushed 2w agoCompare

[ Source](https://github.com/JiFish/parsedown-toc-ext)[ Packagist](https://packagist.org/packages/jifish/parsedown-toc-ext)[ RSS](/packages/jifish-parsedown-toc-ext/feed)WikiDiscussions master Synced 3w ago

READMEChangelog (1)Dependencies (1)Versions (2)Used By (0)

Parsedown TOC Extension
=======================

[](#parsedown-toc-extension)

A simple, lightweight, and modern Table of Contents extension for Parsedown and ParsedownExtra. MIT licenced.

Provides:

- Markdown/HTML TOC generation
- Automatic slugified heading IDs
- Programmatic TOC access
- Configurable depth, numbering, and hierarchy behaviour
- Works with ParsedownExtra
- Manual TOC adjustment

This extension works with both [original parsedown](https://github.com/erusev/parsedown)and the [community fork of Parsedown](https://github.com/parsedown/parsedown).

Inspired by Benjamin Hoegh's [ParsedownToc](https://github.com/BenjaminHoegh/ParsedownToc).

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

[](#installation)

```
composer require jifish/parsedown-toc-ext
```

If you want Parsedown Extra support:

```
composer require erusev/parsedown-extra
```

If you want the community fork of Parsedown, install it first.

```
composer require parsedown/parsedown
```

Basic Usage
-----------

[](#basic-usage)

### Parsedown

[](#parsedown)

```
use jifish\ParsedownTocExt\ParsedownToc;

$parser = new ParsedownToc();

$html = $parser->text($markdown);
$toc = $parser->getToc();
$tocText = $parser->renderToc();
```

### Parsedown Extra

[](#parsedown-extra)

```
use jifish\ParsedownTocExt\ParsedownExtraToc;
$parser = new ParsedownExtraToc();
```

### Substitution of \[TOC\] marker

[](#substitution-of-toc-marker)

```
$html = $parser->text($markdown);
$html = str_replace("[TOC]", $parser->renderToc(), $html);
```

### Custom id generation

[](#custom-id-generation)

If you need you own id generation strategy, you can override `slugify`:

```
use jifish\ParsedownTocExt\ParsedownToc;

class ParsedownTocCustomId extends ParsedownToc
{
    // Generate random ids
    protected function slugify(string $text): string
    {
        return uniqid();
    }
}

$parser = new ParsedownTocCustomId();
```

Heading ID Generation
---------------------

[](#heading-id-generation)

Heading IDs are:

- Lowercased
- Non-alphanumeric characters removed
- Whitespace converted to hyphens
- Guaranteed unique per document, duplicate headings receive numeric suffixes

Example:

```
### My Heading!
```

Becomes:

```
My Heading!
```

Interfaces
==========

[](#interfaces)

### Basic Usage

[](#basic-usage-1)

#### `text(string $markdown): string`

[](#textstring-markdown-string)

As with Parsedown, but adds heading IDs, and builds and stores a new TOC structure.

#### `getToc(): array`

[](#gettoc-array)

Returns the internal TOC structure.

Format:

```
[
    'heading-id' => [
        'level' => 2,
        'text'  => 'Heading Text',
    ],
]
```

- Indexed by generated ID.
- Ordered in document order.
- `level` is the original heading level (`1-6`).

#### `getTocCount(): int`

[](#gettoccount-int)

Returns the number of headings in the TOC.

#### `removeHeading(string $id): void`

[](#removeheadingstring-id-void)

Removes a heading from the TOC by its ID.

#### `renderToc(...)`

[](#rendertoc)

Generates a Markdown-formatted TOC.

```
renderToc(
    bool $asHtml = false,
    bool $collapseSkippedLevels = false,
    ?int $maxDepth = null,
    bool $numbered = false,
    bool $excludeFirstHeading = false
): string
```

**Parameters:**

- `$asHtml` (default `false`)

    If `true`, the generated Markdown TOC is returned as rendered HTML.

    Example:

    ```
    echo $parser->renderToc(asHtml: true);
    ```

    Returns:

    ```

        Title
        ...

    ```
- `$collapseSkippedLevels` (default `false`)

    Controls how heading level jumps are handled. When enabled, large jumps only increase nesting by one level.

    Example:

    ```
    # A
    ### B
    ## C
    ```

    `false` (true depth):

    ```
    - [A](#a)
            - [B](#b)
        - [C](#c)
    ```

    `true` (collapsed hierarchy):

    ```
    - [A](#a)
        - [B](#b)
        - [C](#c)
    ```
- `$maxDepth` (default: `null`)

    Limits how deep headings are included.

    Depth is calculated relative to the lowest heading level in the document.
- `$numbered` (default: `false`)

    Uses ordered list syntax instead of bullet lists. Each nesting level maintains its own numbering sequence.

    Example:

    ```
    1. [Title](#title)
        1. [Install](#install)
        2. [Usage](#usage)
    ```
- `$excludeFirstHeading` (default: `false`)

    Skips the first heading in the document. Useful when the first heading is the page title and should not appear in the TOC. The next visible heading becomes the root of the rendered TOC, while `maxDepth` remains relative to the full document.

#### `hasToc(): bool`

[](#hastoc-bool)

Returns whether the internal TOC currently contains any entries.

### Customising TOC

[](#customising-toc)

#### `appendHeading(int $level, string $text, ?string $id = null): string`

[](#appendheadingint-level-string-text-string-id--null-string)

Manually adds an entry to the end of the internal TOC structure, and returns its id.

This allows you to add headings that are not present in the Markdown source, for use when combining parsed headings with dynamic or generated content, or to generate TOCs without any source markdown.

Note: Calling `text()` will clear the internal TOC.

**Parameters**

- `$level`Heading level (`1-6`). A `ValueError` is thrown if the level is outside this range.
- `$text`The display text used in the TOC.
- `$id` (optional) Custom ID to use instead of generating one from `$text`.

    If omitted, the ID is generated from `$text` using the same slug rules as automatic headings.

    The final ID is always passed through the internal uniqueness check, so collisions are automatically resolved.

Example:

```
$parser = new ParsedownToc();

$parser->addHeader(2, 'Installation');
$parser->addHeader(3, 'Windows');
$parser->addHeader(3, 'Linux');

echo $parser->getTocText();
```

Output:

```
- [Installation](#installation)
    - [Windows](#windows)
    - [Linux](#linux)
```

#### `prependHeading(int $level, string $text, ?string $id = null): string`

[](#prependheadingint-level-string-text-string-id--null-string)

As above, but adds the heading to the top instead.

#### `insertHeadingAfter(string $afterId, int $level, string $text, ?string $id = null): string`

[](#insertheadingafterstring-afterid-int-level-string-text-string-id--null-string)

As above, but inserts the heading directly below `$afterId`. Throws a **ValueError** if the id is not found.

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance89

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity43

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

Unknown

Total

1

Last Release

111d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/1314002?v=4)[Joseph Fowler](/maintainers/JiFish)[@JiFish](https://github.com/JiFish)

---

Top Contributors

[![JiFish](https://avatars.githubusercontent.com/u/1314002?v=4)](https://github.com/JiFish "JiFish (5 commits)")

---

Tags

markdownparsedownparsedown-extraparsedown-extra-pluginparsedown-pluginphpphp-libraryphp8table-of-contentstable-of-contents-generatortableofcontentstoctoc-buildertoc-generatormarkdownparsedownTOCtable-of-contents

### Embed Badge

![Health badge](/badges/jifish-parsedown-toc-ext/health.svg)

```
[![Health](https://phpackages.com/badges/jifish-parsedown-toc-ext/health.svg)](https://phpackages.com/packages/jifish-parsedown-toc-ext)
```

###  Alternatives

[erusev/parsedown-extra

An extension of Parsedown that adds support for Markdown Extra.

84315.1M208](/packages/erusev-parsedown-extra)[benjaminhoegh/parsedown-extended

An extension for Parsedown.

5125.2k1](/packages/benjaminhoegh-parsedown-extended)[tovic/parsedown-extra-plugin

Configurable Markdown to HTML converter with Parsedown Extra.

5934.5k](/packages/tovic-parsedown-extra-plugin)[taufik-nurrohman/parsedown-extra-plugin

Configurable Markdown to HTML converter with Parsedown Extra.

5932.4k](/packages/taufik-nurrohman-parsedown-extra-plugin)[maglnet/magl-markdown

Provides a ZF2 View Helper to render markdown syntax. It uses third-party libraries for the rendering and you can switch between different renderers.

22194.6k4](/packages/maglnet-magl-markdown)[pagerange/metaparsedown

Adds ability to have meta data in markdown files parsed by eursev/parsedown or eruseve/parsedown-extra

2738.1k2](/packages/pagerange-metaparsedown)

PHPackages © 2026

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