ntzwbr/markdown

cebe/markdown 的一个新版本，受 https://github.com/dreikanter/markdown-grid 启发

维护者

详细信息

github.com/Netzweberei/markdown

主页

源代码

问题

安装: 34

依赖: 1

建议者: 0

安全: 0

星标: 1

关注者: 2

分支: 141

开放问题: 0

语言：HTML

0.9.2 2014-02-18 15:53 UTC

Requires

  • php: >=5.4.0
  • lib-pcre: *

Requires (Dev)

MIT 70d24fe88e3cb2795d2a422f3dffd264861bca20

markdownextensiblefastgfmmarkdown-extra

This package is not auto-updated.

Last update: 2024-09-24 02:16:42 UTC

README

Latest Stable Version Total Downloads Build Status Tested against HHVM Code Coverage

Markdown Grid 扩展

Markdown Grid 扩展是一个新版本 cebe/markdown，受 https://github.com/dreikanter/markdown-grid 启发

这是一个用于网格构建的 Markdown 扩展。它提供最小化且直接的语法来创建多列文本布局。默认情况下，该扩展生成与 Twitter Bootstrap 兼容的 HTML 代码，但旨在不依赖于任何模板。它可以配置为使用任何其他 HTML/CSS 框架（例如 Skeleton）或自定义设计。

语法

Markdown 语法扩展相当简单。以下页面源示例定义了一个三列页面片段

-- row 5,2,5 --
First column contains couple of paragraphs. Lorem ipsum dolor sit amet,
consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore
et dolore magna aliqua.

Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi
ut aliquip ex ea commodo consequat.
----
Some images in the middle column:
![One](image-1.png)
![Two](image-2.png)
----
And some **more** text in the _third_ column. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.

[Excepteur](http://excepteur.org ) sint occaecat cupidatat non proident, sunt
in culpa qui officia deserunt mollit anim id est laborum.
-- end --

在 row 指令之后的逗号分隔的数字是可选的列宽定义。此示例使用 12 列 Twitter Bootstrap 网格，因此 "5, 2, 5" 相对于整个页面宽度对应于 "41.5%，17%，41.5%"。

使用方法

在你的 PHP 项目中

要解析你的 Markdown，你只需要两行代码。第一行是选择以下 Markdown 风格之一

  • 原始 Markdown: $parser = new \cebe\markdown\Markdown();
  • Github 风格 Markdown: $parser = new \cebe\markdown\GithubMarkdown();
  • Markdown Extra: $parser = new \cebe\markdown\MarkdownExtra();

下一步是调用 parse() 方法来解析文本，使用完整的 Markdown 语言，或者调用 parseParagraph() 方法来解析仅内联元素。

以下是一些示例

// original markdown and parse full text
$parser = new \cebe\markdown\Markdown();
$parser->parse($markdown);

// use github markdown
$parser = new \cebe\markdown\GithubMarkdown();
$parser->parse($markdown);

// use markdown extra
$parser = new \cebe\markdown\MarkdownExtra();
$parser->parse($markdown);

// use markdown extra with bootstrap-grid
$parser = new \cebe\markdown\BootstrapMarkdown();
$parser->parse($markdown);

// parse only inline elements (useful for one-line descriptions)
$parser = new \cebe\markdown\GithubMarkdown();
$parser->parseParagraph($markdown);

你可以选择以下选项之一设置解析器对象

对于所有 Markdown 风格

  • $parser->html5 = true 以启用 HTML5 输出而不是 HTML4。
  • $parser->keepListStartNumber = true 以启用保持与 Markdown 中指定的有序列表数字。默认行为是始终从 1 开始并递增，而不考虑 Markdown 中的数字。

对于 GithubMarkdown

  • $parser->enableNewlines = true 以将所有换行转换为 <br/> 标签。默认情况下，只有带有两个前导空格的换行才会转换为 <br/> 标签。

命令行脚本

你可以使用它来渲染此 README

bin/markdown README.md > README.html

使用 Github 风格 Markdown

bin/markdown --flavor=gfm README.md > README.html

或使用 Unix 管道将原始 Markdown 描述转换为 html

curl http://daringfireball.net/projects/markdown/syntax.text | bin/markdown > md.html

当你运行 bin/markdown --help 时，你会看到完整的帮助输出

PHP Markdown to HTML converter
------------------------------

by Carsten Brandt <mail@cebe.cc>

Usage:
    bin/markdown [--flavor=<flavor>] [file.md]

    --flavor  specifies the markdown flavor to use. If omitted the original markdown by John Gruber [1] will be used.
              Available flavors:

              gfm   - Github flavored markdown [2]
              extra - Markdown Extra [3]

    --help    shows this usage information.

    If no file is specified input will be read from STDIN.

Examples:

    Render a file with original markdown:

        bin/markdown README.md > README.html

    Render a file using gihtub flavored markdown:

        bin/markdown --flavor=gfm README.md > README.html

    Convert the original markdown description to html using STDIN:

        curl http://daringfireball.net/projects/markdown/syntax.text | bin/markdown > md.html


[1] http://daringfireball.net/projects/markdown/syntax
[2] https://help.github.com/articles/github-flavored-markdown
[3] http://michelf.ca/projects/php-markdown/extra/

扩展语言

Markdown 由两种类型的语言元素组成，我将它们称为块元素和内联元素，类似于你在 HTML 中的 <div> 和 <span>。块元素通常跨越多行，由空白行分隔。最基本的块元素是段落（<p>）。内联元素是添加到块元素内部（即文本内部）的元素。

此 Markdown 解析器允许你通过更改现有元素的行为以及添加新的块元素和内联元素来扩展 Markdown 语言。你可以通过扩展解析器类并添加/覆盖类方法和属性来实现这一点。对于不同的元素类型，有不同的扩展方法，你将在以下章节中看到。

添加块元素

Markdown是逐行解析的，以识别每行非空行作为块元素类型之一。这项工作由indentifyLine()方法执行，该方法接收行数组和当前要识别的行号作为参数。此方法返回识别的块元素名称，然后将其用于解析。以下示例我们将实现对fenced代码块的支持，这是GitHub风格的Markdown的一部分。

<?php

class MyMarkdown extends \cebe\markdown\Markdown
{
	protected function identifyLine($lines, $current)
	{
		// if a line starts with at least 3 backticks it is identified as a fenced code block
		if (strncmp($lines[$current], '```', 3) === 0) {
			return 'fencedCode';
		}
		return parent::identifyLine($lines, $current);
	}

	// ...
}

块元素的解析分为两个步骤

  1. "消耗"属于它的所有行。在大多数情况下，这是从识别的行开始迭代，直到出现空白行。这一步通过名为consume{blockName}()的方法实现，其中{blockName}将被我们在identifyLine()方法中返回的名称替换。消耗方法还接收行数组和当前行号。它将返回两个参数：表示块元素的数组以及下一个要解析的行号。在我们的示例中，我们将这样实现它

     protected function consumeFencedCode($lines, $current)
 {
 	// create block array
 	$block = [
 		'type' => 'fencedCode',
 		'content' => [],
 	];
 	$line = rtrim($lines[$current]);

 	// detect language and fence length (can be more than 3 backticks)
 	$fence = substr($line, 0, $pos = strrpos($line, '`') + 1);
 	$language = substr($line, $pos);
 	if (!empty($language)) {
 		$block['language'] = $language;
 	}

 	// consume all lines until ```
 	for($i = $current + 1, $count = count($lines); $i < $count; $i++) {
 		if (rtrim($line = $lines[$i]) !== $fence) {
 			$block['content'][] = $line;
 		} else {
 			// stop consuming when code block is over
 			break;
 		}
 	}
 	return [$block, $i];
 }

  2. "渲染"元素。在消耗完所有块之后，它们将使用render{blockName}()方法进行渲染

     protected function renderFencedCode($block)
 {
 	$class = isset($block['language']) ? ' class="language-' . $block['language'] . '"' : '';
 	return "<pre><code$class>" . htmlspecialchars(implode("\n", $block['content']) . "\n", ENT_NOQUOTES, 'UTF-8') . '</code></pre>';
 }

    您也可以在这里添加代码高亮。通常，也可以将输出渲染为HTML以外的语言，例如LaTeX。

添加内联元素

添加内联元素与块元素不同，因为它们直接解析出现在文本中的位置。内联元素通过标记来识别，该标记标记内联元素的开始（例如，[将标记链接的可能开始，`将标记内联代码）。

内联标记在inlineMarkers()方法中声明，该方法返回一个从标记到解析方法的映射。当在文本中找到标记时，将调用该方法。该方法将接收从标记位置开始的部分文本作为参数。解析方法将返回一个包含要附加到解析标记中的文本的数组和从输入Markdown中解析的文本偏移量。在下一个标记搜索之前，将删除偏移量之前的所有文本。

例如，我们将添加对GitHub风格的Markdown中的删除线功能的支持

<?php

class MyMarkdown extends \cebe\markdown\Markdown
{
	protected function inlineMarkers()
	{
		$markers = [
			'~~'    => 'parseStrike',
		];
		// merge new markers with existing ones from parent class
		return array_merge(parent::inlineMarkers(), $markers);
	}

	protected function parseStrike($markdown)
	{
		// check whether the marker really represents a strikethrough (i.e. there is a closing ~~)
		if (preg_match('/^~~(.+?)~~/', $markdown, $matches)) {
			return [
			    // return the parsed tag with its content and call `parseInline()` to allow
			    // other inline markdown elements inside this tag
				'<del>' . $this->parseInline($matches[1]) . '</del>',
				// return the offset of the parsed text
				strlen($matches[0])
			];
		}
		// in case we did not find a closing ~~ we just return the marker and skip 2 characters
		return [$markdown[0] . $markdown[1], 2];
	}
}

我可以自由使用这个吗？

此库是开源的，并许可在MIT许可证下使用MIT许可证。这意味着您可以随意使用它，只要您提及我的名字并包含[许可证文件][许可证]。请参阅[许可证][]以获取详细信息。