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 / Parsedown Extra to generate a list of header index (a.k.a. Table of Contents or ToC), from a markdown text given.

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

Script Name	Versions
PHP	Currently it supports PHP version upto PHP 8.3.x. It does not support PHP 8.4 or later.
Parsedown.php	SHA256 Hash: af4a4b29f38b5a00b003a3b7a752282274c969e42dee88e55a427b2b61a2f38f
ParsedownExtra.php	SHA256 Hash: b0c6bd5280fc7dc1caab4f4409efcae9fb493823826f7999c27b859152494be7

[!NOTE] We will support PHP 8.4+ and Parsedown v2 after we finish refactoring the test scripts and the official release of Parsedown v2.

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 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