benjaminhoegh/parsedown-toc

Table of Contents Extension for Parsedown.

v1.5.3 2024-02-03 19:37 UTC

Requires

• php: >=7.4
• erusev/parsedown: ^1.7
• erusev/parsedown-extra: ^0.8.1

Requires (Dev)

• phpunit/phpunit: 9.6.16
• vimeo/psalm: >=5.21.1

MIT

• BenjaminHoegh

• parser
• markdown
• extension

README

ParsedownToc

ParsedownToc is an extension for Parsedown and ParsedownExtra that introduces advanced features for developers working with Markdown. It is based on @KEINOS toc extention

Note

Does not yet include the latest changes in ParsedownExtended v1.2.0

Features:

• Speed: Super-fast processing.
• Configurability: Easily customizable for different use-cases.
• Custom Header IDs: Full support for custom header ids.

Prerequisites:

• Requires Parsedown 1.7.4 or later.

Installation:

Ensure you have Composer installed on your system.

1. Install the ParsedownToc package using Composer:

   composer require benjaminhoegh/ParsedownToc

2. Alternatively, you can download the latest release and include Parsedown.php in your project.

Usage:

Basic example:

<?php
require 'vendor/autoload.php';  // autoload

$content = file_get_contents('sample.md');  // Sample Markdown with '[toc]' tag
$ParsedownToc = new ParsedownToc();

$html = $ParsedownToc->text($content);  // Parses '[toc]' tag to ToC if exists
echo $html;

Separate body and ToC:

<?php
$content = file_get_contents('sample.md');
$ParsedownToc = new \ParsedownToc();

$body = $ParsedownToc->body($content);
$toc  = $ParsedownToc->contentsList();

echo $toc;  // ToC in <ul> list
echo $body; // Main content

Configuration:

The ParsedownToc->setOptions(array $options) method allows you to configure the main class. Below are the available options along with their default values and descriptions:

Option	Type	Default	Description
selectors	array	['h1', 'h2', 'h3', 'h4', 'h5', 'h6']
delimiter	string	-
limit	int	null
lowercase	boolean	true
replacements	array	none
transliterate	boolean	false
urlencode	boolean	false	Uses PHP built-in urlencode and disables all other options.
prefix	string	``	Prefixes anchor with the specified URL.

Methods:

The ParsedownToc class offers several methods for different functionalities:

• text(string $text): Returns the parsed content and [toc] tag(s).
• body(string $text): Returns the parsed content without the [toc] tag.
• contentsList([string $type_return='html']): Returns the ToC in HTML, JSON, or as an array.
  • Optional: Specify the return type as html, json, or array.
• setTocSelectors(array $array): Allows you to set specific selectors.
• setTocDelimiter(string $delimiter): Define a custom delimiter.
• setTocLimit(int $limit): Set a limit for the table of contents.
• setTocLowercase(bool $boolean): Choose whether the output should be in lowercase.
• setTocReplacements(array $replacements): Provide replacements for specific content.
• setTocTransliterate(bool $boolean): Specify if transliterations should be made.
• setTocUrlencode(bool $boolean): Decide if you want to use PHP's built-in urlencode.
• setTocBlacklist(array $blacklist): Blacklist specific IDs from header anchor generation.
• setTocPrefix(string $url): Set a specific URL prefix for anchors.
• setTocTag(string $tag='[tag]'): Set a custom ToC markdown tag.
• setTocId(string $id): Set a custom ID for the table of contents.

Custom Anchors

If you want to use your own logic for creating slugs for the headings, you can do so by using setCreateAnchorIDCallback.

Example using cocur's slugify:

$ParsedownToc->setCreateAnchorIDCallback(function($text, $level) {
    $slugify = new Slugify();
    return $slugify->slugify($text);
});