PHP Markdown Extended
Yet another PHP parser for the markdown (extended) syntax., (*1)
, (*2)
, (*3)
, (*4)
, (*5)
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., (*6)
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., (*7)
README contents:, (*8)
Installation
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., (*9)
Raw PHP package
First, you can clone the GitHub
repository and include it "as is" in your project:, (*10)
$ git clone https://github.com/e-picas/markdown-extended.git
You can also download an archive
from GitHub:, (*11)
$ wget --no-check-certificate https://github.com/e-picas/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:, (*12)
require_once 'path/to/package/src/bootstrap.php';
Using Composer
Another way to use the package, if you are a Composer user,
is to add it to your requirements in your composer.json file:, (*13)
"picas/markdown-extended": "dev-master"
The namespace will be automatically added to the project's Composer's autoloader., (*14)
Using a standalone version
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., (*15)
The archive is stored in a specific phar-latest branch on the repository:, (*16)
$ wget --no-check-certificate https://github.com/e-picas/markdown-extended/archive/phar-latest.tar.gz
$ tar -xvf phar-latest.tar.gz
$ cd phar-latest
Locally
If you only need the archive for a local project, you can copy it where you
want:, (*17)
$ 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:, (*18)
$ ./install.sh ~/bin false
Globally
For a complete global install, run:, (*19)
$ sudo ./install.sh /usr/local
Usage
An HTML demonstration and the code documentation are available on the "dev" branch., (*20)
Usage for writers
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)., (*21)
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/e-picas/markdown-extended/blob/dev/demo/MD_syntax.md., (*22)
Usage for developers
The source code documentation of the last stable release can also be found online at
http://docs.ateliers-pierrot.fr/markdown-extended/., (*23)
The MarkdownExtended package can be simply call writing:, (*24)
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)., (*25)
The returned $content variable is actually a \MarkdownExtended\API\ContentInterface
object but you can write it directly using:, (*26)
echo $content; // shortcut for $content->getContent()
To get the part you need from the content, write:, (*27)
$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):, (*28)
// 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
https://github.com/e-picas/markdown-extended/blob/master/doc/DOCUMENTATION.md.
Its manpage version is embedded in the package running:, (*29)
$ man ./man/markdown-extended.7.man
Command line usage
A command line interface is proposed with the package running:, (*30)
$ ./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., (*31)
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:, (*32)
$ man ./man/markdown-extended.3.man
The developer documentation is also available as a manpage running:, (*33)
$ man ./man/markdown-extended.7.man
Examples of cli usage:, (*34)
# 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
...
Old parsers compatibility
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:, (*35)
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 ;), (*36)
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., (*37)
As the sources are hosted on a GIT repository on
GitHub, you can modify it, to
ameliorate a feature or correct an error. Please read the CONTRIBUTING.md
file of the package
for more info., (*38)
License
This software, as the original Markdown, is licensed under the terms of the
BSD-3-Clause license.
Please see the LICENSE file for a full text., (*39)
You can use, transform and distribute this software and its dependencies as you wish, as
long as you mention the copyrights below:, (*40)
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-2024 Pierre Cassat & contributors
<http://picas.fr/>
All rights reserved.
Wallogit.com
