https://github.com/keinos/parsedown-extension_table-of-contents
✅ Simple Parsedown extension/plugin to generate a list of ToC (Table of Contents) from headings of a Markdown file.
https://github.com/keinos/parsedown-extension_table-of-contents
markdown-parser parsedown parsedown-extra-plugin php
Last synced: 28 days ago
JSON representation
✅ Simple Parsedown extension/plugin to generate a list of ToC (Table of Contents) from headings of a Markdown file.
- Host: GitHub
- URL: https://github.com/keinos/parsedown-extension_table-of-contents
- Owner: KEINOS
- License: mit
- Created: 2018-01-22T08:49:39.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-02-19T01:03:33.000Z (about 2 years ago)
- Last Synced: 2024-10-30T10:44:35.655Z (6 months ago)
- Topics: markdown-parser, parsedown, parsedown-extra-plugin, php
- Language: Shell
- Homepage:
- Size: 95.7 KB
- Stars: 13
- Watchers: 4
- Forks: 5
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://travis-ci.org/KEINOS/parsedown-extension_table-of-contents "Travis CI Build Status")
[](https://github.com/KEINOS/parsedown-extension_table-of-contents/blob/master/.travis.yml "Supported PHP Version")
[](https://github.com/erusev/parsedown/releases "Supported Parsedown Version")
[](https://packagist.org/packages/keinos/parsedown-toc "View in Packagist")
# Parsedown ToC Extension
Listing Table of Contents Extension for [Parsedown](http://parsedown.org/).
This [simple PHP file](https://github.com/KEINOS/parsedown-extension_table-of-contents/blob/master/Extension.php) extends [Parsedown Vanilla](https://github.com/erusev/parsedown) / [Parsedown Extra](https://github.com/erusev/parsedown-extra) to generate a list of header index (a.k.a. Table of Contents or ToC), from a markdown text given.
```bash
composer require keinos/parsedown-toc
```
```php
$ cat ./parse_sample.php
text($text_markdown);
echo $html . PHP_EOL;
```
```shellsession
$ cat ./SAMPLE.md
[toc]
---
# One
Something about One
## Two
Something about Two
# One2
Something about One2
```
```bash
$ php ./parse_sample.php
One
Something about One
Two
Something about Two
One2
Something about One2
```
With the `toc()` method, you can get just the "ToC".
```php
body($text_markdown);
$toc = $Parsedown->toc();
echo $toc . PHP_EOL; // Table of Contents in
- list
echo $body . PHP_EOL; // Main body
```
- 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)`:
- Returns the parsed content WITHOUT parsing `[toc]` tag.
- Required argument `$text`: Markdown string to be parsed.
- `toc([string $type_return='string'])`:
- Returns the ToC, the table of contents, in HTML or JSON.
- Option argument:
- `$type_return`:
- `string` or `json` can be specified. `string`=HTML, `json`=JSON.
- Default `string`
- Alias method: `contentsList(string $type_return)`
- `setTagToc(string $tag='[tag]')`:
- Sets user defined ToC markdown tag. Use this method before `text()` or `body()` method if you want to use the ToC tag rather than the "`[toc]`".
- Empty value sets the default ToC tag.
- Available since v1.1.2
- Other Methods:
- All the public methods of `Parsedown` and/or `Parsedown Extend` are available to use.
- Note: As of v1.1.0 the old alias class: `Extension()` is deprecated.
## Online Demo
- [https://paiza.io/projects/0TghplxParLqyrP1tjAg6g?locale=en-us](https://paiza.io/projects/0TghplxParLqyrP1tjAg6g?locale=en-us) @ paiza.IO
## Install
### Via Composer
If you are familiar to [composer](https://en.wikipedia.org/wiki/Composer_(software)), the package manager for PHP, then install it as below:
```bash
# Current stable
composer require keinos/parsedown-toc
# Latest
composer require keinos/parsedown-toc:dev-master
```
- Usage: [See sample project](https://github.com/KEINOS/parsedown-extension_table-of-contents/tree/master/samples/composer)
### Manual Install (Download the script)
You can download the '[Extension.php](https://github.com/KEINOS/parsedown-extension_table-of-contents/blob/master/Extension.php)' file from the below URL. Place it anywhere you like to include.
```bash
https://KEINOS.github.io/parsedown-extension_table-of-contents/Extension.php
```
- **NOTE:** Since this is an extension of [Parsedown](https://parsedown.org/), you need to download and include `Parsedown.php` as well.
- Usage: [See sample project](https://github.com/KEINOS/parsedown-extension_table-of-contents/tree/master/samples/download)
```bash
# Download via cURL
curl -O https://KEINOS.github.io/parsedown-extension_table-of-contents/Extension.php
```
```bash
# Download via PHP
php -r "copy('https://KEINOS.github.io/parsedown-extension_table-of-contents/Extension.php', './Extension.php');"
```
## Sample Usage
- See: [./samples/](./samples/)
## Advanced Usage (Using Parsedown Extra)
As of Parsedown ToC Extension v1.1.1, you can use the [anchor identifiers](https://michelf.ca/projects/php-markdown/extra/#header-id) for [Parsedown Extra](https://github.com/erusev/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.
```markdown
# SampleHead1 {#self-defined-head1}
Sample text of head 1
---
[Link back to header 1](#self-defined-head1)
```
With the above markdown the generated ToC will be as below. Note that the anchor is changed to the specified one.
```html
```
- Note that you need to require/include the Parsedown Extra as well.
## 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](https://github.com/erusev/parsedown/wiki) @ GitHub
- [Issues of this extension](https://github.com/KEINOS/parsedown-extension_table-of-contents/issues) @ GitHub
- [Issues of Parsedown](https://github.com/erusev/parsedown/issues) @ GitHub
- [Issues of Parsedown Extra](https://github.com/erusev/parsedown-extra/issues) @ GitHub
- Authors:
- [KEINOS and the contributors](https://github.com/KEINOS/parsedown-extension_table-of-contents/graphs/contributors) @ GitHub
- Licence:
- [MIT](https://github.com/KEINOS/parsedown-extension_table-of-contents/blob/master/LICENSE)