README

另一个用于Markdown (扩展)语法的PHP解析器。

PHP Markdown Extended 是一个PHP解析器，用于将Markdown文本文件或字符串转换为HTML或其他格式。这个Markdown解析器的新版本试图遵循 扩展语法规范，并且符合PHP-5.3规范，并且高度可定制。

您可以在PHP脚本中使用此包，就像通常使用PHP应用程序一样，也可以作为一个独立的命令行实用工具。CLI接口具有大量选项，并且完全有文档。

README内容

• 安装
  • 原始PHP包
  • 使用Composer
  • 使用独立版本
    • 本地
    • 个人
    • 全局
• 使用方法
  • 作家使用方法
  • 开发者使用方法
  • 命令行使用
  • 旧解析器兼容性
• 开源 & 社区
• 许可证

安装

您可以用多种方式在此作品中使用此包。请注意，它需要至少5.3.3版本的PHP。

原始PHP包

首先，您可以克隆 GitHub 仓库，并将其“原样”包含到您的项目中

$ git clone https://github.com/e-picas/markdown-extended.git

您也可以从GitHub下载一个 存档

$ wget --no-check-certificate https://github.com/e-picas/markdown-extended/archive/master.tar.gz
$ tar -xvf master.tar.gz

然后，要使用包类，您只需要包含其 启动器，它将注册其命名空间到当前运行时环境

require_once 'path/to/package/src/bootstrap.php';

使用Composer

如果您是 Composer 用户，另一个使用包的方法是将其添加到您的 composer.json 文件中的要求中

"picas/markdown-extended": "dev-master"

命名空间将自动添加到项目的Composer 自动加载器 中。

使用独立版本

最后，如果您计划将解析器作为一个单独的二进制文件使用，您可以直接使用嵌入整个源代码作为独立二进制文件的 PHAR存档 (~220Kb)。它的用法与下面描述的 bin/markdown-extended 脚本相同。

存档存储在仓库的特定 phar-latest 分支上

$ 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

本地

如果您只需要本地项目的存档，您可以将它复制到您想要的位置

$ cp bin/markdown-extended.phar your/project/path/
$ php your/project/path/markdown-extended.phar ...

个人

要将二进制文件安装到您用户的二进制文件中

$ ./install.sh ~/bin false

全局

对于完整的全局安装，运行

$ sudo ./install.sh /usr/local

使用方法

HTML演示和代码文档可在“dev”分支上找到。

作家使用方法

为了符合 扩展 Markdown语法，作家可以按照在 http://cheatsheet.aboutmde.org/ 中描述的规则构建他们的内容（所有基本Markdown规则仍然有效和有效）。

对于完整示例和测试文件，您可以参考包的 demo/MD_syntax.md 文件；最新版本可以在 http://github.com/e-picas/markdown-extended/blob/dev/demo/MD_syntax.md 中找到。

开发者使用方法

最新稳定版本的源代码文档也可以在http://docs.ateliers-pierrot.fr/markdown-extended/ 上找到。

MarkdownExtended 包可以简单地通过编写代码来调用。

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

这将加载到 $content 中的原始 Markdown 源（文件内容或字符串）的解析版本。

返回的 $content 变量实际上是一个 \MarkdownExtended\API\ContentInterface 对象，但您可以直接使用它来编写。

echo $content;          // shortcut for $content->getContent()

要从内容中获取所需的部分，请编写：

$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
;

您还可以将 \MarkdownExtended\Parser 对象用作过程性非静态对象（这实际上是上述静态方法所真正做的）。

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

更完整的用法文档可以在包的文档中找到（doc/DOCUMENTATION.md）。您可以在此处在线阅读。它的 manpage 版本嵌入在运行的包中。

$ man ./man/markdown-extended.7.man

命令行使用

包运行时提供了一个命令行界面。

$ ./bin/markdown-extended --help

该界面允许解析一个或多个文件，从源中提取一些信息，将结果写入文件以及一些其他操作。提供了一组大量选项来定制转换。

在包的 man/ 目录中提供了一个完整的 manpage，其 markdown 源在文档中可用（doc/MANPAGE.md）。要阅读它，请运行：

$ man ./man/markdown-extended.3.man

开发者文档也可以作为一个 manpage 运行。

$ man ./man/markdown-extended.7.man

cli 使用示例

# 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
...

旧解析器兼容性

为了保持包与旧版本的 Markdown 兼容，嵌入了一个与常用 Markdown($content) 函数兼容的接口；要使用它，只需包含包中的 src/markdown.php 文件。

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]);

这样，您可能能够在不进行太多工作的情况下更改您的 Markdown 解析器，并且我希望结果是更好的；)

开源 & 社区

此解析器是免费软件，可在 BSD 许可证 下使用；您可以自由使用它，无论是个人用途还是商业用途，根据您的需求修改其源代码，自由分发您的工作并将其提交给社区，只要您提供有关其最初作者的信息。

由于源代码托管在 GIT 存储库 GitHub 上，您可以修改它以改进功能或纠正错误。有关更多信息，请阅读包的 CONTRIBUTING.md 文件。

许可证

此软件，如同原始 Markdown，根据 BSD-3-Clause 许可证 的条款进行许可。请参阅 LICENSE 文件以获取全文。

您可以按自己的意愿使用、转换和分发此软件及其依赖项，只要您提及以下版权信息。

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.