README

概述

Markdown-X是一个命令行工具，允许您从php源代码中提取功能片段并将它们放入markdown块中。您可以对提取的片段的输出进行引用，并告诉Markdown X将输出放置在最终的markdown中的任何位置。

安装

您可以选择克隆此存储库或使用composer

composer require flsouto/mdx

注意：由于这是一个应用程序而不是库，因此不会添加到您的自动加载器中。

为了方便起见，您可能希望为进程脚本创建一个别名

alias mdx='php /path/to/flsouto/mdx/process.php'

用法

假设您已经编写了一些库代码以及一个测试

<?php

	// Contents of my_library.php
	function extractWords($input){
		return explode(' ', $input);
	}

	// Contents of tests.php
	require_once('my_library.php');
	function testCase1(){
		$string = "Input to be tested";
		$words = extractWords($string);
		assert(count($words)==4);
	}

现在您想要为您的库编写一些文档，展示extractWords函数的使用。如果您像我一样，您不喜欢重复自己，那么您就会意识到测试代码 已经包含了您想在文档中展示的片段。这就是mdx发挥作用的地方

	require_once('my_library.php');
	function testCase1(){
		#mdx:snippet1
		$string = "Input to be tested";
		$words = extractWords($string);
		#/mdx
		assert(count($words)==4);
	}

在上面的代码中，我们已经包装了我们要提取的片段，并将其命名为"snippet1"。为了在markdown-x模板中调用该代码，您必须像这样引用它

Take a look at this code snippet:
#mdx:snippet1

作为一个例子，我将上面的模板保存到一个名为README.mdx的文件中，并在终端运行以下命令

mdx README.mdx tests.php > README.md

上述操作生成了一个README.md文件，内容如下

	Take a look at this code snippet:
	```php
	<?php
	$string = "Input to be tested";
	$words = extractWords($string);		
	```

因此，它提取了片段并将其放置在markdown中。太棒了。

提取片段的输出

这非常有用。比如说，您不仅想要展示您库的使用，还想要展示它产生的内容。您必须修改您的源代码，并告诉markdown-x片段的输出应该是什么

	require_once('my_library.php');
	function testCase1(){
		#mdx:snippet1
		$string = "Input to be tested";
		$words = extractWords($string);
		#/mdx print_r($words)
		assert(count($words)==4);
	}

注意说#/mdx print_r($words)的行。这告诉markdown-x 'snippet1'片段的输出应该是print_r($words)。现在，在您的模板中，您可以使用-o选项调用该输出

Take a look at this code snippet:
#mdx:snippet1

The output is:
#mdx:snippet1 -o

让我们运行mdx

mdx README.mdx tests.php > README.md

REAMDE.md的内容如下（注意，输出命令print_r($words)现在已集成到片段中）

	Take a look at this code snippet:
	
	```php
	<?php
	$string = "Input to be tested";
	$words = extractWords($string);
	print_r($words)
	```
	The output is:
	```
	Array
	(
		[0] => Input
		[1] => to
		[2] => be
		[3] => tested
	)
	```

在片段的不同位置放置输出

您可以在片段的末尾生成输出，而不是在中部生成，通过使用#mdx:o标志。下面是示例

	require_once('my_library.php');
	function testCase1(){
		#mdx:snippet1
		$string = "Input to be tested";
		#mdx:o var_dump($string)
		$words = extractWords($string);
		#/mdx
		assert(count($words)==4);
	}

当提取snippet1时，#mdx:o var_dump($string)行将不会显示，但在输出被调用时会执行。

跳过一行

如果您只想完全忽略/删除片段中的一行，可以使用#mdx:skip标志。下面是示例，将删除片段中的some_dev_stuff()行

	require_once('my_library.php'); 
	
	some_dev_stuff(); #mdx:skip
	
	// etc...

整理HTML输出

如果片段的输出是HTML格式，您可以使用httidy选项在-o旁边，以便使HTML看起来更漂亮（带有缩进等）

#mdx:snippet_that_produces_html -o httidy

输出

```html
	<div>
	  <span></span>
	  <div></div>
	</div>
```

注意：此选项自动将代码类型设置为'html'，以便使用正确的语法高亮器。

调用头

有时，为了使一个片段正常工作，它需要额外的包含和/或其他东西，比如在脚本的顶部定义的常量或"使用"语句。使用markdown-x，您可以使用#mdx:h指令标记一行为所需的头

#mdx:h autoload
require_once('vendor/autoload.php');

#mdx:h alias
use Some\Library as Alias;

// etc...

在上面的例子中，我们标记了两个标题："autoload" 和 "alias"。现在，当你从这个文件调用代码片段时，这两行将直接跟在 php 开头标签之后。此外，当调用代码片段的输出时，这些标题将与提取的代码片段一起执行，从而使一切按预期工作。

注意： "autoload" 和 "alias" 是我任意选择的名称。你可以选择任何其他名称来标记你的标题行。

防止标题显示在文档中

尽管有些标题是必要的，但在文档的某些部分，它们可能会显得明显且冗余，因此你可能希望在调用代码片段时抑制它们。

Take a look at this code (I have ommited some top statements for sake of brevity)
#mdx:snippet1 -h:autoload,alias

如果你想跳过 autoload 但保留 alias

#mdx:snippet1 -h:autoload

默认隐藏标题

如果你想确保一个标题语句始终执行但从不显示，则可以使用 "hidden" 选项，该选项应放在标题名称之后，如下所示

#mdx:h autoload hidden
require_once('vendor/autoload.php');

防止 php 标签显示在文档中

与抑制标题相同，你也可以抑制 php 开头标签的出现

#mdx:snippet1 -php

-php 选项也可以与 -h 选项一起使用

#mdx:snippet1 -php -h:alias

上述操作会将代码片段放入 markdown 中，而不包含 php 开头标签和 alias 标题。

重复之前使用的选项

在文档的某个时刻，你可能需要反复使用相同的选项，如下所示

See this example:
#mdx:snippet1 -php -h:alias,autoload

See another example:
#mdx:snippet2 -php -h:alias,autoload

See yet another example:
#mdx:snippet3 -php -h:alias,autoload

好消息是，你可以使用特殊的 idem 选项来避免这种重复性工作。此标志将复制最后使用的 mdx 命令中使用的相同选项

See this example:
#mdx:snippet1 -php -h:alias,autoload

See another example:
#mdx:snippet2 idem

See yet another example:
#mdx:snippet3 idem

结语

想看看实际生产中使用的示例？那么请查看这个 markdown-x 模板及其生成的 markdown 文件

如果你想在实践中看到这个转换，所需的步骤如下

使用此文档中安装部分的说明安装 mdx
下载示例仓库，请参阅https://github.com/flsouto/pipe
切换到下载的仓库的根目录
运行 mdx README.mdx tests/PipeTest.php

你应该能在你的控制台中看到转换的结果。

flsouto / mdx

维护者

详细信息