This addon is not compatible with Cockpit CMS v2.
See also Cockpit CMS v1 docs, Cockpit CMS v1 repo and Cockpit CMS v2 docs, Cockpit CMS v2 repo.
Cache, task lists and ToC support for markdown conversion with Cockpit CMS
This addon replaces the current Parsedown and ParsedownExtra libraries with later versions and it adds two Parsedown extensions: ParsedownToC and ParsedownTasks.
It also uses a cache of already converted content to speed things up. Cached files are in the tmp
folder.
Copy this repository into /addons
and name it BetterMarkdown
or use the cli.
cd path/to/cockpit
git clone https://github.com/raffaelj/cockpit_BetterMarkdown.git addons/BetterMarkdown
cd path/to/cockpit
./cp install/addon --name BetterMarkdown --url https://github.com/raffaelj/cockpit_BetterMarkdown/archive/master.zip
Make sure, that the path to cockpit addons is defined in your projects' composer.json
file.
{
"name": "my/cockpit-project",
"extra": {
"installer-paths": {
"addons/{$name}": ["type:cockpit-module"]
}
}
}
cd path/to/cockpit-root
composer create-project --ignore-platform-reqs aheinze/cockpit .
composer config extra.installer-paths.addons/{\$name} "type:cockpit-module"
composer require --ignore-platform-reqs raffaelj/cockpit-bettermarkdown
path/to/cockpit/config/config.php
:
<?php
return [
'app.name' => 'markdown test',
'bettermarkdown' => [
'parser' => 'extended', // (string) parsedown|extra|extended - default: extended
'cache' => false, // cache is still active, but rebuild is forced --> useful for debugging
// change settings for ParsedownToC
// see: https://github.com/BenjaminHoegh/parsedownToc#configuration
'toc' => [
'selectors' => ['h2', 'h3', 'h4', 'h5', 'h6'], // omit h1 from toc
// blacklist existing ids in your frontend
'blacklist' => [
'nav', // turns to 'nav-1'
'top',
],
// array of regexes for text replacements - before heading ids are generated
'replacements' => [
'/^old-id$/' => 'new-id',
],
],
'cached_toc_format' => 'tree', // (string) flat|tree - default: flat
// transform the cached toc in tree format with cleaner output
'tree_toc' => [
'replace_keys' => [
'text' => 'title',
],
'unset_keys' => ['level', 'id'],
],
// add classes to task lists
'tasks' => [
'classUnchecked' => 'parsedown-task-list parsedown-task-list-open',
'classChecked' => 'parsedown-task-list parsedown-task-list-close',
],
],
];
Markdown:
# Markdown Test
[toc]
## Usage
do something
## To do
* [x] test
* [ ] deploy
Conversion:
$html = $app->module('cockpit')->markdown($md);
html output:
<h1 id="markdown-test">Markdown Test</h1>
<div id="toc"><ul>
<li><a href="#usage">Usage</a></li>
<li><a href="#to-do">To do</a></li>
</ul></div>
<h2 id="usage">Usage</h2>
<p>do something</p>
<h2 id="to-do">To do</h2>
<ul>
<li class="parsedown-task-list parsedown-task-list-close">
<input type="checkbox" checked disabled /> test
</li>
<li class="parsedown-task-list parsedown-task-list-open">
<input type="checkbox" disabled /> deploy
</li>
</ul>
After converting some markdown, two files are added to the tmp folder.
{$hash}.md.html
{$hash}.md.toc.json
$html = $app->module('cockpit')->markdown($md);
$hash = md5($md);
$cachepath = "tmp:///{$hash}.md.toc.json";
if ($app->filestorage->has($cachepath)) {
$toc = \json_decode($app->filestorage->read($cachepath), true);
}
print_r($toc);
License: MIT, author: Raffael Jesche, www.rlj.me
Used libraries:
- "erusev/parsedown-extra": "0.8.1", MIT
- "erusev/parsedown": "^1.7.4", MIT
- "benjaminhoegh/parsedown-toc": "^1.4.3", MIT
- "raffaelj/parsedown-tasks": "^0.1.0", MIT