github markdown php,Ciconia：一个支持Github Markdown风格的Markdown解析器

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.

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

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**');

//

Markdown is awesome

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**');

//

Markdown is awesome

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**');

//

Markdown is awesome

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](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.

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

$ciconia = new \Ciconia\Ciconia();

$ciconia->addExtension(new MentionExtension());

echo $ciconia->render('@kzykhys my email address is example@example.com!');

Output

@kzykhys my email address is example@example.com!

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

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.

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

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)