README

League/CommonMark 的扩展，用于向 Markdown 添加 '短代码'。

短代码是 Markdown 文档中的文本片段，由一对或三对花括号限定，并替换为所需的任何内容。短代码有两种类型：行内和块（行内和块短代码的名称不能相同；即您在设计短代码时必须决定每个短代码如何使用）。

行内短代码有一个花括号，格式为 {name|attr=val}，并出现在段落或列表项等内部。例如，这里 cite 是短代码的名称，并且它有一个属性

There are over 300 distinct breeds{cite|Kris2008} of goat.

块短代码有三个花括号，格式为 {{{name|attr=val}}}，可选有一个主体；其属性与行内短代码相同。这里 quotation 是短代码，它有一个属性和一个两行主体

{{{quotation|source=Q2934
The goat is a member of the animal family Bovidae and the tribe Caprini,
meaning it is closely related to the sheep.
}}}

短代码可以有零个或多个属性。属性由竖线 | 分隔，并且可以通过添加等号（如果没有名称，它们将从 1 开始编号）来赋予名称。

在编译时，短代码将被替换为短代码处理器中指定的 HTML（或其他内容）。有关如何设置 CommonMark 环境的更多信息，请参见下面的使用。

安装

使用 Composer 安装

$ composer require samwilson/commonmark-shortcodes

使用方法

使用具有 shortcodes 配置键的 CommonMark 环境对象

$environment = new Environment([
    'shortcodes' => [
        'shortcodes' => [
            'myshortcode' => /* callback one */
            'myshortcode2' => /* callback two */
        ],
    ],
]);
$environment->addExtension(new CommonMarkCoreExtension());

然后添加 ShortcodeExtension 并开始转换 Markdown

$environment->addExtension(new ShortcodeExtension());
$converter = new MarkdownConverter($environment);
echo $converter->convert('Markdown *goes here*.')->getContent();

回调函数是您定义短代码输出的地方。每个回调函数接受一个参数（一个 Shortcode 对象）并返回一个字符串，该字符串将被插入到输出中，替换短代码。

例如，以下 Markdown

Lorem {smallcaps|ipsum}.

可以与以下短代码配置配对

[
    'smallcaps' => function (Shortcode $shortcode) {
        return '<span style="font-variant:small-caps">'
            . $shortcode->getAttr(1)
            . '</span>';
    },
]

以生成以下输出

<p>Lorem <span style="font-variant:small-caps">ipsum</span></p>

有关功能示例，请参阅 examples/ 目录，如果您有任何问题，请报告它们。

许可证

本程序是自由软件：您可以根据自由软件基金会发布的 GNU 通用公共许可证的条款重新分发和/或修改它，许可证版本为 3，或者（根据您的选择）任何较新版本。

本程序按照“希望它有用”的原则分发，但不提供任何保证；甚至不保证适销性或特定用途的适用性。有关详细信息，请参阅 GNU 通用公共许可证。

您应该已经收到与程序一起的 GNU 通用公共许可证副本。如果没有，请参阅 https://gnu.ac.cn/licenses/

samwilson / commonmark-shortcodes

维护者

详细信息

README

安装

使用方法

许可证