Popularity
4.2
Stable
Activity
0.0
Stable
356
19
31

Description

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.

Code Quality Rank: L5
Monthly Downloads: 16
Programming language: PHP
License: MIT License
Tags: Markup     Parser     CLI     Markdown    
Latest version: v1.0.3

Ciconia alternatives and similar libraries

Based on the "Markup" category.
Alternatively, view Ciconia alternatives based on common mentions on social networks and blogs.

Do you think we are missing an alternative of Ciconia or a related project?

Add another 'Markup' Library

README

Ciconia - A New Markdown Parser for PHP

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

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](src/Ciconia/Extension)

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](src/Ciconia/Renderer/RendererInterface.php)

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:

  1. Setting the bin-dir configuration setting in composer.json
  2. 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)


*Note that all licence references and agreements mentioned in the Ciconia README section above are relevant to that project's source code only.