Yet another PHP parser for the markdown (*extended*) syntax
Yet another PHP parser for the markdown (extended) syntax.
PHP Markdown Extended is a PHP parser to transform Markdown text files or strings in HTML or other formats. This new version of a Markdown parser tries to follow the extended syntax specifications and is PHP-5.3 compliant and highly customizable.
You can use this package in PHP scripts just as usual (for PHP apps) and also like a standalone command line utility. The CLI interface is interactive with a large set of options and fully documented.
- Open-Source & Community
You can use this package in your work in many ways. Please note that it requires a running PHP version of 5.3.3 minimum.
First, you can clone the GitHub repository and include it "as is" in your project:
$ git clone https://github.com/piwi/markdown-extended.git
You can also download an archive from GitHub:
$ wget --no-check-certificate https://github.com/piwi/markdown-extended/archive/master.tar.gz $ tar -xvf master.tar.gz
Then, to use the package classes, you just need to include its bootstrapper which will register its namespaces in current runtime environment:
Another way to use the package, if you are a Composer user,
is to add it to your requirements in your
The namespace will be automatically added to the project's Composer's autoloader.
Finally, if you plan to use the parser as a single binary, you can use a
PHAR archive directly, which embeds
the whole source as a standalone binary (~220Kb). Its usage is the same as the
bin/markdown-extended script described below.
The archive is stored in a specific
phar-latest branch on the repository:
$ wget --no-check-certificate https://github.com/piwi/markdown-extended/archive/phar-latest.tar.gz $ tar -xvf phar-latest.tar.gz $ cd phar-latestLocally
If you only need the archive for a local project, you can copy it where you want:
$ cp bin/markdown-extended.phar your/project/path/ $ php your/project/path/markdown-extended.phar ...Personally
To install the binary in your user's binaries:
$ ./install.sh ~/bin falseGlobally
For a complete global install, run:
$ sudo ./install.sh /usr/local
An HTML demonstration and the code documentation are available on the "dev" branch.
To be compliant with the extended Markdown syntax, writers may construct their contents following the rules described at http://cheatsheet.aboutmde.org/ (all basic markdown rules are still available and valid).
For a full example and a test file, you can refer to the
demo/MD_syntax.md file of the package ;
the latest version can be found at http://github.com/piwi/markdown-extended/blob/dev/demo/MD_syntax.md.
The source code documentation of the last stable release can also be found online at http://docs.ateliers-pierrot.fr/markdown-extended/.
MarkdownExtended package can be simply call writing:
use \MarkdownExtended\MarkdownExtended; // load the namespace $options = array( /* ... */ ); // parser options, see documentation // parse a string or a file content $content = MarkdownExtended::parse( "my markdown string" OR 'my-markdown-file.md' , $options ); // parse a string $content = MarkdownExtended::parseString( "my markdown string" , $options ); // parse a file content $content = MarkdownExtended::parseSource( 'my-markdown-file.md' , $options );
This will load in
$content the parsed version of your original Markdown
source (file content or string).
$content variable is actually a
object but you can write it directly using:
echo $content; // shortcut for $content->getContent()
To get the part you need from the content, write:
$content ->getContent() // the full content ->getCharset() // a guessed character set ->getTitle() // the guessed title ->getBody() // the body ->getMetadata() // the metadata as array ->getNotes() // the notes as array ;
You can also use the
\MarkdownExtended\Parser object as a procedural non-static
object (this is in fact what the static methods above really do):
// create an instance with custom options $parser = new \MarkdownExtended\Parser( $options ); // parse a string $content = $parser->transform( "my markdown string" ); // parse a file content $content = $parser->transformSource( 'my-markdown-file.md' );
A more complete usage documentation is available in the package's documents
doc/DOCUMENTATION.md). You can read it online at
Its manpage version is embedded in the package running:
$ man ./man/markdown-extended.7.man
A command line interface is proposed with the package running:
$ ./bin/markdown-extended --help
The interface allows to parse one or more files, extract some information from sources, write the results in files and some other stuff. A large set of options are available to customize the transformation.
A complete manpage is available in the package's
man/ directory and its markdown source is
available in its documents (
doc/MANPAGE.md). To read it, run:
$ man ./man/markdown-extended.3.man
The developer documentation is also available as a manpage running:
$ man ./man/markdown-extended.7.man
Examples of cli usage:
# transform a simple string $ ./bin/markdown-extended "my **markdown** _extended_ string" my <strong>markdown</strong> <em>extended</em> string # transform a file content with output to STDOUT $ ./bin/markdown-extended my-markdown-file.md ... # transform a file content with output in file $ ./bin/markdown-extended --output=my-transformed-markdown.html my-markdown-file.md ... # generate the manpage itslef $ ./bin/markdown-extended -f man -o man/markdown-extended.man doc/MANPAGE.md ...
To keep the package compatible with old versions of Markdown, an interface is embedded
with the common
Markdown($content) function ; to use it, just include the file
src/markdown.php of the package:
require_once 'path/to/src/markdown.php'; // to get result of a string parsing: echo Markdown($string [, $options]); // to get result of a file content parsing: echo MarkdownFromSource($file_name [, $options]);
This way, you may be able to change your Markdown parser without so much work and, I hope so, a better result ;)
This parser is a free software, available under BSD license ; you can freely use it, for yourself or a commercial use, modify its source code according to your needs, freely distribute your work and propose it to the community, as long as you let an information about its first authors.
This software, as the original Markdown, is licensed under the terms of the
BSD-3-Clause open source license.
Please see the
LICENSE file for a full text.
You can use, transform and distribute this software and its dependencies as you wish, as long as you mention the copyrights below:
Markdown Copyright (c) 2003-2006 John Gruber <http://daringfireball.net/> All rights reserved. PHP Markdown & Extra Copyright (c) 2004-2009 Michel Fortin <http://michelf.com/> All rights reserved. Multi Markdown Copyright (c) 2005-2009 Fletcher T. Penney <http://fletcherpenney.net/> All rights reserved. PHP Markdown Extended Copyright (c) 2008-2015 Pierre Cassat & contributors <http://e-piwi.fr/> All rights reserved.