Ciconia - A New Markdown Parser for PHP
, (*1)
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., (*2)
Try Demo / Docs / Supported Syntax / API Reference, (*3)
Requirements
Installation
create a composer.json, (*7)
``` json
{
"require": {
"kzykhys/ciconia": "~1.0.0"
}
}, (*8)
and run
php composer.phar install, (*9)
Usage
-----
### Traditional Markdown
``` php
use Ciconia\Ciconia;
$ciconia = new Ciconia();
$html = $ciconia->render('Markdown is **awesome**');
//
Markdown is awesome, (*10)
Github Flavored Markdown
To activate 6 gfm features:, (*11)
``` php
use Ciconia\Ciconia;
use Ciconia\Extension\Gfm;, (*12)
$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());, (*13)
$html = $ciconia->render('Markdown is awesome');, (*14)
//, (*15)
Markdown is awesome, (*16)
### 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 |
``` php
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:, (*17)
``` php
use Ciconia\Ciconia;
use Ciconia\Renderer\XhtmlRenderer;, (*18)
$ciconia = new Ciconia(new XhtmlRenderer());
$html = $ciconia->render('Markdown is awesome');, (*19)
//, (*20)
Markdown is awesome, (*21)
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
<?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., (*22)
``` php
<?php, (*23)
require DIR . '/vendor/autoload.php';, (*24)
$ciconia = new \Ciconia\Ciconia();
$ciconia->addExtension(new MentionExtension());
echo $ciconia->render('@kzykhys my email address is example@example.com!');, (*25)
Output
``` html
<p><a href="http://example.com/user/kzykhys">@kzykhys</a> my email address is example@example.com!</p>
Each extension handles string as a Text object. See API section of kzykhys/Text., (*26)
Events
Possible events are:, (*27)
| 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, (*28)
See events and timing information, (*29)
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., (*30)
See Ciconia\Renderer\RendererInterface, (*31)
Command Line Interface
Usage
Basic Usage: (Outputs result to STDOUT), (*32)
ciconia /path/to/file.md
Following command saves result to file:, (*33)
ciconia /path/to/file.md > /path/to/file.html
Or using pipe (On Windows in does't work):, (*34)
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:, (*35)
Yes, there are two ways an alternate vendor binary location can be specified:, (*36)
- Setting the bin-dir configuration setting in composer.json
- Setting the environment variable COMPOSER_BIN_DIR
http://getcomposer.org/doc/articles/vendor-binaries.md, (*37)
Using PHAR version
You can also use single phar file, (*38)
ciconia.phar /path/to/file.md
If you prefer access this command globally, download ciconia.phar and move it into your PATH., (*39)
mv ciconia.phar /usr/local/bin/ciconia
Testing
Install or update dev dependencies., (*40)
php composer.phar update --dev
and run phpunit, (*41)
License
The MIT License, (*42)
Contributing
Feel free to fork this repository and send a pull request. (A list of contributors), (*43)
Author
Kazuyuki Hayashi (@kzykhys), (*44)
Wallogit.com
