Ciconia - A New Markdown Parser for PHP
The Markdown parser for PHP5.4, it is fully extensible. Ciconia is the collection of extension, so you can replace, add or remove each parsing mechanism.
Try Demo / Docs / Supported Syntax / API Reference
-
Based on John Gruber's Markdown.pl
-
Github Flavored Markdown support (disabled by default)
- Multiple underscores in words
- New lines
- Fenced code blocks
- Task lists
- Table
- URL Autolinking
-
Tested with karlcow/markdown-testsuite
Requirements
- PHP5.4+
- Composer
Installation
create a composer.json
{
"require": {
"kzykhys/ciconia": "~1.0.0"
}
}
and run
php composer.phar install
Usage
Traditional Markdown
use Ciconia\Ciconia;
$ciconia = new Ciconia();
$html = $ciconia->render('Markdown is **awesome**');
// <p>Markdown is <em>awesome</em></p>
Github Flavored Markdown
To activate 6 gfm features:
use Ciconia\Ciconia;
use Ciconia\Extension\Gfm;
$ciconia = new Ciconia();
$ciconia->addExtension(new Gfm\FencedCodeBlockExtension());
$ciconia->addExtension(new Gfm\TaskListExtension());
$ciconia->addExtension(new Gfm\InlineStyleExtension());
$ciconia->addExtension(new Gfm\WhiteSpaceExtension());
$ciconia->addExtension(new Gfm\TableExtension());
$ciconia->addExtension(new Gfm\UrlAutoLinkExtension());
$html = $ciconia->render('Markdown is **awesome**');
// <p>Markdown is <em>awesome</em></p>
Options
| Option | Type | Default | Description |
|---|---|---|---|
| tabWidth | integer | 4 | Number of spaces |
| nestedTagLevel | integer | 3 | Max depth of nested HTML tags |
| strict | boolean | false | Throws exception if markdown contains syntax error |
use Ciconia\Ciconia;
$ciconia = new Ciconia();
$html = $ciconia->render(
'Markdown is **awesome**',
['tabWidth' => 8, 'nestedTagLevel' => 5, 'strict' => true]
);
Rendering HTML or XHTML
Ciconia renders HTML by default. If you prefer XHTML:
use Ciconia\Ciconia;
use Ciconia\Renderer\XhtmlRenderer;
$ciconia = new Ciconia(new XhtmlRenderer());
$html = $ciconia->render('Markdown is **awesome**');
// <p>Markdown is <em>awesome</em></p>
Extend Ciconia
How to Extend
Creating extension is easy, just implement Ciconia\Extension\ExtensionInterface.
Your class must implement 2 methods.
void register(Ciconia\Markdown $markdown)
Register your callback to markdown event manager. Ciconia\Markdown is instance of Ciconia\Event\EmitterInterface (looks like Node.js's EventEmitter)
string getName()
Returns the name of your extension. If your name is the same as one of core extension, it will be replaced by your extension.
Extension Example
This sample extension turns @username mentions into links.
<?php
use Ciconia\Common\Text;
use Ciconia\Extension\ExtensionInterface;
class MentionExtension implements ExtensionInterface
{
/**
* {@inheritdoc}
*/
public function register(\Ciconia\Markdown $markdown)
{
$markdown->on('inline', [$this, 'processMentions']);
}
/**
* @param Text $text
*/
public function processMentions(Text $text)
{
// Turn @username into [@username](http://example.com/user/username)
$text->replace('/(?:^|[^a-zA-Z0-9.])@([A-Za-z]+[A-Za-z0-9]+)/', function (Text $w, Text $username) {
return '[@' . $username . '](http://example.com/user/' . $username . ')';
});
}
/**
* {@inheritdoc}
*/
public function getName()
{
return 'mention';
}
}
Register your extension.
<?php
require __DIR__ . '/vendor/autoload.php';
$ciconia = new \Ciconia\Ciconia();
$ciconia->addExtension(new MentionExtension());
echo $ciconia->render('@kzykhys my email address is [email protected]!');
Output
<p><a href="http://example.com/user/kzykhys">@kzykhys</a> my email address is [email protected]!</p>
Each extension handles string as a Text object. See API section of kzykhys/Text.
Events
Possible events are:
| Event | Description |
|---|---|
| initialize | Document level parsing. Called at the first of the sequence. |
| block | Block level parsing. Called after initialize |
| inline | Inline level parsing. Generally called by block level parsers. |
| detab | Convert tabs to spaces. Generally called by block level parsers. |
| outdent | Remove one level of line-leading tabs or spaces. Generally called by block level parsers. |
| finalize | Called after block |
See the source code of Extensions
See events and timing information
Create your own Renderer
Ciconia supports HTML/XHTML output. but if you prefer customizing the output, just create a class that implements Ciconia\Renderer\RendererInterface.
See Ciconia\Renderer\RendererInterface
Command Line Interface
Usage
Basic Usage: (Outputs result to STDOUT)
ciconia /path/to/file.md
Following command saves result to file:
ciconia /path/to/file.md > /path/to/file.html
Or using pipe (On Windows in does't work):
echo "Markdown is **awesome**" | ciconia
Command Line Options
--gfm Activate Gfm extensions
--compress (-c) Remove whitespace between HTML tags
--format (-f) Output format (html|xhtml) (default: "html")
--lint (-l) Syntax check only (lint)
Where is the script?
CLI script will be installed in vendor/bin/ciconia by default. To change the location:
Yes, there are two ways an alternate vendor binary location can be specified:
- Setting the bin-dir configuration setting in composer.json
- Setting the environment variable COMPOSER_BIN_DIR
http://getcomposer.org/doc/articles/vendor-binaries.md
Using PHAR version
You can also use single phar file
ciconia.phar /path/to/file.md
If you prefer access this command globally, download ciconia.phar and move it into your PATH.
mv ciconia.phar /usr/local/bin/ciconia
Testing
Install or update dev dependencies.
php composer.phar update --dev
and run phpunit
License
The MIT License
Contributing
Feel free to fork this repository and send a pull request. (A list of contributors)
Author
Kazuyuki Hayashi (@kzykhys)
14.3k Jan 8, 2023
2.4k Jan 1, 2023
989 Dec 16, 2022
522 Dec 29, 2022
22 Dec 5, 2022
56 Nov 26, 2022
1.2k Dec 31, 2022
665 Jan 4, 2023
358 Nov 26, 2022
194 Dec 27, 2022
0 Feb 22, 2022
1 Oct 29, 2021
5 May 29, 2022
801 Dec 28, 2022
687 Jan 4, 2023
1 Feb 2, 2022
3.3k Jan 1, 2023
2k Dec 27, 2022