Skip to content

Commit b061e7a

Browse files
KEINOSKEINOS
committed
docs: add basic usage of ParsedownExtra in README
1 parent 82b5488 commit b061e7a

2 files changed

Lines changed: 88 additions & 6 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
vendor/
2-
composer.lock
2+
/composer.lock
33
/Parsedown.php
44
/ParsedownExtra.php
55
.phpdoc

‎README.md‎

Lines changed: 87 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,14 @@
88

99
Listing Table of Contents Extension for [Parsedown](http://parsedown.org/).
1010

11-
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.
11+
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) / [ParsedownExtra](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.
1212

1313
- For PHP 8.3+ users: see [supported PHP version](#requirements) for more details.
1414

1515
## Basic Usage
1616

17+
<details><summary>Parsedown Vanilla</summary><br />
18+
1719
```php
1820
<?php
1921

@@ -71,6 +73,86 @@ $ php ./index.php
7173
</ul>
7274
```
7375

76+
</details>
77+
78+
<details><summary>Parsedown Extra</summary><br />
79+
80+
```php
81+
<?php
82+
83+
// Include the Parsedown, ParsedownExtra and ToC extension
84+
require_once('Parsedown.php');
85+
require_once('ParsedownExtra.php');
86+
require_once('Extension.php');
87+
88+
// Extended markdown data sample
89+
$textMarkdown = <<<EOL
90+
# Head1 {#self-defined-head1}
91+
92+
You can include inline HTML tags<br>in the markdown text.
93+
94+
<div markdown="1">
95+
And use the markdown syntax inside HTML Blocks.
96+
</div>
97+
98+
| Header1 | Header2 |
99+
| ------- | ------- |
100+
| Table syntax | as well |
101+
102+
## 見出し2 {#self-defined-head2-1}
103+
104+
You can customize the anchor IDs of non-ASCII characters, such as Japanese characters, to more readable ones.
105+
106+
EOL;
107+
108+
// Instanciate the Parsedown with ToC extension
109+
$parser = new \ParsedownToc();
110+
111+
// Get the parsed HTML
112+
$html = $parser->text($textMarkdown);
113+
114+
// Get the Table of Contents
115+
$ToC = $parser->contentsList();
116+
117+
echo $html . PHP_EOL;
118+
echo "---" . PHP_EOL;
119+
echo $ToC . PHP_EOL;
120+
```
121+
122+
```shellsession
123+
$ php ./index.php
124+
<h1 id="self-defined-head1" name="self-defined-head1">Head1</h1>
125+
<p>You can include inline HTML tags<br>in the markdown text.</p>
126+
<div>
127+
<p>And use the markdown syntax inside HTML Blocks.</p>
128+
</div>
129+
<table>
130+
<thead>
131+
<tr>
132+
<th>Header1</th>
133+
<th>Header2</th>
134+
</tr>
135+
</thead>
136+
<tbody>
137+
<tr>
138+
<td>Table syntax</td>
139+
<td>as well</td>
140+
</tr>
141+
</tbody>
142+
</table>
143+
<h2 id="self-defined-head2-1" name="self-defined-head2-1">見出し2</h2>
144+
<p>You can customize the anchor IDs of non-ASCII characters, such as Japanese characters, to more readable ones.</p>
145+
---
146+
<ul>
147+
<li><a href="#self-defined-head1">Head1</a>
148+
<ul>
149+
<li><a href="#self-defined-head2-1">見出し2</a></li>
150+
</ul></li>
151+
</ul>
152+
```
153+
154+
</details>
155+
74156
- For more examples see the [examples](https://github.com/KEINOS/parsedown-extension_table-of-contents/tree/master/examples) directory.
75157

76158
## Installation
@@ -172,23 +254,23 @@ $ php ./parse_sample.php
172254

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

175-
However, the latest stable release of `Parsedown` 1.7.4 do not fully support PHP 8.4. And `Parsedown Extra` 0.8.1 do not fully support PHP 8.2 or later. Which throws deprecation warnings of PHP.
257+
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 8.2 or later. Which throws deprecation warnings of PHP.
176258

177259
### Stable Combination
178260

179-
To use the stable released version of `Parsedown` 1.7.4 and `Parsedown Extra` 0.8.1, you need to use between PHP 5.5 and PHP 8.1.
261+
To use the stable released version of `Parsedown` 1.7.4 and `ParsedownExtra` 0.8.1, you need to use between PHP 5.5 and PHP 8.1.
180262

181263
With later PHP versions you will get several deprecation warnings.
182264

183265
| Script Name | Versions |
184266
| :-- | :-- |
185267
| PHP | [![Static Badge](https://img.shields.io/badge/%3E%3D5.5%20%3C%3D8.1-blue?logo=php&label=PHP)](https://github.com/KEINOS/parsedown-extension_table-of-contents/blob/master/composer.json#L19 "Supported PHP Version") |
186268
| Parsedown.php | [![Parsedown Version Badge](https://img.shields.io/badge/Parsedown-%3D1.7.4-blue)](https://github.com/erusev/parsedown/releases "Supported Parsedown Version") <br />SHA256 Hash: `af4a4b29f38b5a00b003a3b7a752282274c969e42dee88e55a427b2b61a2f38f` |
187-
| ParsedownExtra.php | [![ParsedownExtra Version Badge](https://img.shields.io/badge/ParsedownExtra-%3D0.8.1-blue)](https://github.com/erusev/parsedown-extra/releases "Supported Parsedown Extra Version") <br />SHA256 Hash: `b0c6bd5280fc7dc1caab4f4409efcae9fb493823826f7999c27b859152494be7` |
269+
| ParsedownExtra.php | [![ParsedownExtra Version Badge](https://img.shields.io/badge/ParsedownExtra-%3D0.8.1-blue)](https://github.com/erusev/parsedown-extra/releases "Supported ParsedownExtra Version") <br />SHA256 Hash: `b0c6bd5280fc7dc1caab4f4409efcae9fb493823826f7999c27b859152494be7` |
188270

189271
### Last-gasp Effort Combination
190272

191-
We have patched versions of `Parsedown` 1.7.4 and `Parsedown Extra` 0.8.1 to support PHP 8.4, the current latest PHP version.
273+
We have patched versions of `Parsedown` 1.7.4 and `ParsedownExtra` 0.8.1 to support PHP 8.4, the current latest PHP version.
192274

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

0 commit comments

Comments
 (0)