README

扩展 PHP Markdown 解析器，针对 ATK14 项目优化。它基于 Michel Fortin 的 PHP Markdown Extra 构建。

最初它是为“Doctor Ink”项目（简称“Drink”）开发的。

请注意！它处于 alpha 状态。它与 ATK14 框架有一些关联，因此不能轻松用于其他项目。

功能

DrinkMarkdown 扩展 PHP Markdown Extra，以

• 自动将 URL 和电子邮件文本转换为可点击链接
• 提供可选的 HTML 纯化
• 提供源代码语法高亮显示
• 改进表格渲染
• iobjects（待解释）

基本用法

$dm = new DrinkMarkdown([
  "table_class" => "table", // the CSS class for tables, default is "table table-bordered table-hover"
  "html_purification_enabled" => true, // default is true
  "temp_dir" => "/path/to/temp", // default is constant TEMP or sys_get_temp_dir()
  "iobjects_processing_enabled" => true, // insertable objects processing, default is true
  "urlize_text" => true, // reconstruct missing links to urls or emails? default is true
  "shortcodes_enabled" => true, // whether to enable or disable processing of shortcodes, default is true
  "shortcode_autowiring_enabled" => true, // Smarty shortcodes are being registered automatically
]);

$html = $dm->transform($markdown);

在 ATK14 模板中的使用

DrinkMarkdown 包包含两个在 ATK14 模板中可用的辅助程序。

如果您有可信的内容

{$text|markdown nofilter} {* or *}
{!$text|markdown}

如果您有不安全的内容，例如用户评论

{$comment|safe_markdown nofilter} {* or *}
{!$comment|safe_markdown}

短代码

DrinkMarkdown 可以通过扩展：所谓的短代码进行扩展。

有三种类型的短代码

• 块短代码
• 行内块短代码
• 函数短代码

短代码的渲染可以通过回调函数或 Smarty（ATK14 框架中使用的模板引擎）插件提供。块短代码对应于 Smarty 块插件，函数短代码对应于 Smarty 函数插件。块短代码和行内块短代码之间的区别在于，块短代码会影响整个段落，而行内块短代码可以在段落或句子内部操作。

内置短代码

DrinkMarkdown 包含用于将文本组织成列的块短代码。

[row]

[col]
### Column 1
This is text of the first column.
[/col]

[col]
### Column 2
This is text of the second column.
[/col]

[col]
### Column 3
This is text of the third column.
[/col]

[/row]

请参见这里的活示例

短代码 div 渲染

[div class="teaser" id="id_teaser"]

## Hello World!

Welcome to this very nice place.

[/div]

行内块短代码 span 渲染 元素，具有给定属性。同样，短代码内的 markdown 语法将被解释。

## Hello [span class="world"]World[/span]!

Welcome to this very nice place.

自定义短代码

$dm = new DrinkMarkdown();

1. 回调

$dm->registerBlockShortcode("alert", function($columns,$params){
  $params += [
    "type" => "primary"
  ];
  return "<div class=\"alert alert-$params[type]\" role=\"alert\">$content</div>";
});

$dm->registerInlineBlockShortcode("upper", function($content,$params){ return strtoupper($content); });

$dm->registerFunctionShortcode("name", function($params){
  $params += [
    "gender" => "male"
  ];
  return $params["gender"]=="female" ? "Samantha Doe" : "John Doe";
});

2. Smarty 插件

$dm->registerBlockShortcode("alert");
$dm->registerInlineBlockShortcode("upper");
$dm->registerFunctionShortcode("name");

如果在短代码注册期间未指定回调，则需要相应的 Smarty 插件。请注意插件命名约定。

<?php
// file: app/helpers/block.drink_shortcode__alert.php
function smarty_block_drink_shortcode__alert($params,$content,$template,&$repeat){
  if($repeat){ return; }

  $params += array(
    "type" => "primary"
  );

  return "<div class=\"alert alert-$params[type]\" role=\"alert\">$content</div>";
}

<?php
// file: app/helpers/block.drink_shortcode__upper.php
function smarty_block_drink_shortcode__upper($params,$content,$template,&$repeat){
  if($repeat){ return; }

  return strtoupper($content);
}

<?php
// file: app/helpers/function.drink_shortcode__name.php
function smarty_function_drink_shortcode__name($params,$template){
  $params += array(
    "gender" => "male"
  );

  return $params["gender"]=="female" ? "Samantha Doe" : "John Doe";
}

现在，一切准备就绪。以下 markdown 文本...

## This is welcome screen!

[alert type="info"]
Welcome [upper][name gender="female"][/upper]
[/alert]

...将被渲染为

<h2>This is welcome screen!</h2>

<div class="alert alert-info">
<p>Welcome SAMANTHA DOE!</p>
</div>

短代码自动连接

默认情况下，所有找到的 Smarty 插件都被注册为函数短代码或块短代码。

例如，如果文件 app/helpers/function.drink_shortcode__current_year.php 存在，则可以使用 [current_year] 短代码而无需先前注册。

如果不需要短代码自动连接，则可以在构造函数中通过“shortcode_autowiring_enabled”选项禁用它。

安装

只需使用 Composer

cd path/to/your/atk14/project/
composer require atk14/drink-markdown

可选地，您可以链接（或复制和编辑）辅助程序到您的项目。

ln -s ../../vendor/atk14/drink-markdown/src/app/helpers/block.markdown.php app/helpers/
ln -s ../../vendor/atk14/drink-markdown/src/app/helpers/block.safe_markdown.php app/helpers/
ln -s ../../vendor/atk14/drink-markdown/src/app/helpers/modifier.markdown.php app/helpers/
ln -s ../../vendor/atk14/drink-markdown/src/app/helpers/modifier.safe_markdown.php app/helpers/
ln -s ../../vendor/atk14/drink-markdown/src/app/helpers/block.drink_shortcode__row.php app/helpers/
ln -s ../../vendor/atk14/drink-markdown/src/app/helpers/block.drink_shortcode__col.php app/helpers/
mkdir -p app/views/shared/helpers/drink_shortcodes
ln -s ../../../../../vendor/atk14/drink-markdown/src/app/views/shared/helpers/drink_shortcodes/_row.tpl app/views/shared/helpers/drink_shortcodes/
ln -s ../../../../../vendor/atk14/drink-markdown/src/app/views/shared/helpers/drink_shortcodes/_col.tpl app/views/shared/helpers/drink_shortcodes/

许可

DrinkMarkdown 是免费软件，根据MIT 许可证条款发布