Download the PHP package keinos/parsedown-toc without Composer

Parsedown ToC Extension

Listing Table of Contents Extension for Parsedown.

This simple PHP file extends Parsedown Vanilla / ParsedownExtra to generate a list of header index (a.k.a. Table of Contents or ToC), from a markdown text given.

• For PHP 8.4+ users: see supported PHP version for more details.

Basic Usage

• For more examples see the examples directory.

Installation

This extension, ParsedownToC, is a single PHP file. Download and place it in the same directory as the Parsedown.php file (optionally place the ParsedownExtra.php file if you are using it).

Via Composer

We also support Composer for installation and convenience.

Requirements

PardesownToC itself supports PHP 5.5 up-to current latest PHP 8.4.

However, the latest stable release of Parsedown 1.7.4 do not fully support PHP 8.4. And ParsedownExtra 0.8.1 do not fully support PHP 7.1 or later. Which throws deprecation warnings of PHP.

Stable Combination

To use both the stable released versions of Parsedown 1.7.4 and ParsedownExtra 0.8.1, you need to use between PHP 5.5 and PHP 7.0.

With later PHP versions you will get several deprecation warnings.

Script Name	Versions
PHP
Parsedown.php	SHA256 Hash: af4a4b29f38b5a00b003a3b7a752282274c969e42dee88e55a427b2b61a2f38f
ParsedownExtra.php	SHA256 Hash: b0c6bd5280fc7dc1caab4f4409efcae9fb493823826f7999c27b859152494be7

Last-gasp Effort Combination

For PHP 8.4 or higher users: We have patched versions of Parsedown 1.7.4 and ParsedownExtra 0.8.1 to support PHP 8.4, the current latest PHP version and above.

These patched versions do not have any new features or refactoring made. Only the deprecation warnings from PHP are removed.

Use these combinations if you want to use the exact same features as the stable version with the latest PHP version.

Script Name	Versions
PHP
Parsedown.php (patched)	SHA256 Hash: b81a67cdd55e984bacc5fa5be84a15794de94b71841a18a9028a13ab9a41756a (no new feature and refactoring)
ParsedownExtra.php (patched)	SHA256 Hash: 2873b8eac69aae9d8422dba1efc53c143ab85b570bfe8429035eeb47014cb5ca (no new feature and refactoring)

[!NOTE] We are not supporting Parsedown v2 or above until the official beta release.

Class Info and Methods

For more details, please refer to the PHP Doc reference.

• Main Class: ParsedownToC()
  • Arguments: none
  • Methods:
  • text(string $text):
    • Returns the parsed content and [toc] tag(s) parsed as well
    • Required argument:
    • $text: Markdown string to be parsed
  • body(string $text [, bool $omit_toc_tag=false]):
    • Returns the parsed content WITHOUT parsing [toc] tag
    • Required argument:
    • $text: Markdown string to be parsed
    • Optional argument:
    • $omit_toc_tag: If true, the [toc] tag will be excluded from the output
    • Default: false
    • Available since v1.3.0
  • contentsList([string $type_return='string']):
    • Returns the ToC, the table of contents, in HTML or JSON.
    • Optional argument:
    • $type_return: Specifies the returned format
      • "string" or "json" can be specified. string=HTML, json=JSON.
      • Default "string"
  • setTagToc(string $tag='[tag]'):
    • Sets user defined ToC markdown tag. Empty value sets the default tag
    • Default: "[toc]"
    • Available since v1.1.2
    • Note: Use this method before text() or body() method if you want to use the ToC tag rather than the "[toc]"
  • Other Methods:
  • All the public methods of Parsedown and/or Parsedown Extend are available to use
  • Note: As of ParsedownToC v1.1.0 the old alias class Extension() is deprecated

Online Demo

• https://paiza.io/projects/0TghplxParLqyrP1tjAg6g?locale=en-us @ paiza.IO

Advanced Usage (Using Parsedown Extra)

As of ParsedownToC v1.1.1, you can use the anchor identifiers for Parsedown Extra.

With this feature, you can specify the anchor name you like. Useful if the headings are in UTF-8 (not in ASCII) and to make it readable. Such as placing the "go back" links in a page.

With the above markdown the generated ToC will be as below. Note that the anchor is changed to the specified one.

• Note that you need to require/include the Parsedown Extra as well.

Testing

Eventhough we are migraing the tests to PHPUnit, currently we use hand-made test scripts to run the unit tests via bash.

Testing using docker (docker compose)

Testing locally

To run the tests:

[!IMPORTANT] This test will download/install dependencies such as: Parsedown.php, ParsedownExtra.php, git, jq, curl and bash if not installed. So please run this test in a safe Unix-like environment (docker for example).

References

• Repo:
  • Source Code: https://github.com/KEINOS/parsedown-extension_table-of-contents @ GitHub
  • Archived Package: https://packagist.org/packages/keinos/parsedown-toc @ Packagist
• Support:
  • Parsedown's Wiki @ GitHub
  • Issues of this extension @ GitHub
  • Issues of Parsedown @ GitHub
  • Issues of Parsedown Extra @ GitHub
• Authors:
  • KEINOS and the contributors @ GitHub
• Licence:
  • MIT