benjaminhoegh / parsedown-toc
Table of Contents Extension for Parsedown.
Fund package maintenance!
paypal.me/BenjaminHoegh
www.buymeacoffee.com/BenjaminHoegh
Requires
- php: >=7.4
- erusev/parsedown: ^1.7
Requires (Dev)
- phpunit/phpunit: 9.6.16
- vimeo/psalm: >=5.21.1
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.
-
Install the ParsedownToc package using Composer:
composer require benjaminhoegh/ParsedownToc
-
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:
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
, orarray
.
- Optional: Specify the return type as
- 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.
- setTocUrl(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); });