MarkdownPP 技术文档

1. 安装指南

为了使用 MarkdownPP，您需要从 GitHub 上下载源代码或者克隆仓库，然后手动运行安装脚本。

pip install MarkdownPP

2. 项目使用说明

MarkdownPP 是一个 Python 模块，用于在 John Gruber 定义的出色 Markdown 语法基础上添加扩展功能。这些扩展主要集中在创建更大的技术文档，无需使用像 Docbook 那样重量级和语法复杂的工具。

MarkdownPP 使用一组可选择的模块来对原始文档应用一系列转换，最终生成一个包含章节或特性的新 Markdown 文档，这些章节或特性如果手动生成或维护将会非常繁琐。

为了使 MarkdownPP 能够处理文档，建议将文件命名为 .mdpp 扩展名，以便 MarkdownPP 能够生成同名但扩展名为 .md 的文档。例如，本文档的原始格式命名为 "readme.mdpp"，而 MarkdownPP 生成的文档命名为 "readme.md"，以便 GitHub 能够找到并处理该文档。

3. 项目API使用文档

以下是 MarkdownPP 的一些主要模块及其功能：

Includes

该模块用于包含其他文件的内容。使用 !INCLUDE "path/to/filename" 形式的行来替换指定文件的内容。

IncludeURLs

用于包含远程文件的内容，使用 !INCLUDEURL "http://your.domain/path/to/filename" 形式的行。

IncludeCode

用于包含本地代码文件的内容，并围绕代码添加 GFM 栅栏。

Table of Contents

生成文档的目录，使用 !TOC 在文档中插入目录。

Reference

生成参考文献列表，使用 !REF 在文档中插入引用。

LaTeX Rendering

渲染 LaTeX 代码，使用 $ ... $ 包围 LaTeX 代码。

YouTube Embeds

将 YouTube 视频链接转换为截图，并添加链接。

4. 项目安装方式

如前所述，您可以通过以下命令安装 MarkdownPP：

pip install MarkdownPP

如果您有一个名为 foo.mdpp 的文件，可以通过以下命令生成预处理后的文件 foo.md：

markdown-pp foo.mdpp -o foo.md

如果不指定输出文件名，结果将打印到 stdout，可以重定向到其他命令。

默认情况下，所有可用模块都是启用的。您可以通过 -e 参数指定要排除的模块列表：

markdown-pp foo.mdpp -o foo.md -e latexrender,youtubembed

要查看使用说明，包括启用的模块列表，可以使用 -h 或 --help 参数：

markdown-pp --help