The Markdown parser for PHP5.4

Installs: 13 932

Dependents: 16

Stars: 350

Watchers: 22

Forks: 29

Open Issues: 27

Language: PHP

v1.0.3 2014-01-23 08:14 UTC


Latest Stable Version Build Status Coverage Status SensioLabsInsight

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


  • PHP5.4+
  • Composer


create a composer.json

    "require": {
        "kzykhys/ciconia": "~1.0.0"

and run

php composer.phar install


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>


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.


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](
        $text->replace('/(?:^|[^a-zA-Z0-9.])@([A-Za-z]+[A-Za-z0-9]+)/', function (Text $w, Text $username) {
            return '[@' . $username . '](' . $username . ')';

     * {@inheritdoc}
    public function getName()
        return 'mention';

Register your extension.


require __DIR__ . '/vendor/autoload.php';

$ciconia = new \Ciconia\Ciconia();
$ciconia->addExtension(new MentionExtension());
echo $ciconia->render('@kzykhys my email address is!');


<p><a href="">@kzykhys</a> my email address is!</p>

Each extension handles string as a Text object. See API section of kzykhys/Text.


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


Basic Usage: (Outputs result to STDOUT)

ciconia /path/to/

Following command saves result to file:

ciconia /path/to/ > /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:

  1. Setting the bin-dir configuration setting in composer.json
  2. Setting the environment variable COMPOSER_BIN_DIR

Using PHAR version

You can also use single phar file

ciconia.phar /path/to/

If you prefer access this command globally, download ciconia.phar and move it into your PATH.

mv ciconia.phar /usr/local/bin/ciconia


Install or update dev dependencies.

php composer.phar update --dev

and run phpunit


The MIT License


Feel free to fork this repository and send a pull request. (A list of contributors)


Kazuyuki Hayashi (@kzykhys)