多项目扩展

MultiProject 是 Foliant 的扩展，用于从多个来源生成文档。MultiProject由三个部分组成：

• foliant.config用于解析!fromYAML 标记的包扩展；
• 命令的 CLI 扩展src；
• RepoLink 预处理器。

安装

$ pip install foliantcontrib.multiproject

配置扩展来解析!from标签

此扩展解析!from项目配置中的 YAML 标签，并将标签的值替换chaptres为相关子项目的部分。

嵌套子项目以递归方式处理。

配置扩展的使用

子项目位置可以指定为本地路径，也可以指定为带有可选修订版（分支名称、提交哈希或其他引用）的 Git 存储库。

chapters项目配置中的部分示例：

chapters:
    - index.md
    - !from local_dir
    - !from https://github.com/foliant-docs/docs.git
    - !from https://github.com/some_other_group/some_other_repo.git#develop

在构建文档超级项目之前，Multiproject 扩展调用 Foliant 将每个子项目构建到pre目标中，然后将构建的子项目的目录移动到超级项目的源目录（通常称为src）。

限制：

• 同级子项目的目录名必须唯一；
• 多项目和所有子项目的源目录应具有相同的名称；它们也应该位于相应项目的“根”目录中；
• 多项目和所有子项目的配置文件应具有相同的名称；
• 来自远程 Git 存储库的子项目不需要在每次构建之前重新克隆，但本地子项目在每次构建之前都会复制到缓存中；
• 如果顶层项目的“根”目录的路径包含.multiprojectcache目录作为它的一部分，这是不可取的。

src命令的 CLI 扩展

此扩展支持命令src备份 Foliant 项目的源目录（通常称为src）并从准备好的备份中恢复它。

需要备份源目录，因为 MultiProject 扩展通过将构建的子项目的目录移动到其中来修改此目录。

CLI 扩展的使用

要备份源目录，请使用以下命令：

$ foliant src backup

要从备份中恢复源目录，请使用以下命令：

$ foliant src restore

您可以使用该--config选项来指定 Foliant 项目的自定义配置文件名。默认情况下，使用名称foliant.yml：

$ foliant src backup --config alternative_config.yml

--path您也可以使用该选项指定 Foliant 项目的根目录。如果未指定，将使用当前目录。

RepoLink 预处理器

这个预处理器允许在每个 Markdown 源中添加一个指向 Git 存储库中相关文件的超链接。将预处理器应用于子项目允许从单个站点的不同页面（例如，使用 MkDocs 生成）获取指向不同存储库的链接。

默认情况下，预处理器模拟 MkDocs 行为。预处理器生成具有特定属性的 HTML 超链接，并将链接插入到文档的第一个标题之后。默认行为可能会被覆盖。

repo_url预处理器支持与edit_uriMkDocs相同的选项。

预处理器的使用

要启用预处理器，请添加repolink到preprocessors项目配置中的部分：

preprocessors:
    - repolink

预处理器有许多选项：

preprocessors:
    - repolink:
        repo_url: https://github.com/foliant-docs/docs/
        edit_uri: /blob/master/src/
        link_type: html
        link_location: after_first_heading
        link_text: ""
        link_title: View the source file
        link_html_attributes: "class=\"md-icon md-content__icon\" style=\"margin: -7.5rem 0\""
        targets:
            - pre

repo_url : 相关存储库的 URL。默认值为空字符串；在这种情况下，预处理器不适用。尾部斜线不影响。

edit_uri ：存储库中每个文件的 URL 的修订相关部分。默认值为/blob/master/src/。前导和尾随斜杠不影响。

link_type : 链接类型：HTML ( html) 或 Markdown ( markdown)。默认值为html。

link_location : 在文件中放置超链接。默认情况下，超链接放置在第一个标题之后，并在其前后添加换行符 ( after_first_heading)。其他值：before_content——超链接放在文档内容之前，之后提供换行符；after_content——超链接放置在文档内容之后，换行之前添加；defined_by_tag——文档内容中遇到的标签<repo_link></repo_link>被超链接替换。

link_text ：超链接文本。默认值为Edit this page。

link_title : 超链接标题（titleHTML 属性的值）。默认值也是Edit this page. link_type该选项仅在设置为时生效html。

link_html_attributes : 超链接的附加 HTML 属性。通过将 CSS 与class属性和/或style属性结合使用，您可以自定义超链接的呈现方式。默认值为空字符串。link_type该选项仅在设置为时生效html。

targets ：预处理器的允许目标。如果未指定（默认情况下），预处理器将应用于所有目标。

您可以使用系统环境变量覆盖edit_uriconfig 选项的值。FOLIANT_REPOLINK_EDIT_URI它在一些不稳定的测试或登台环境中很有用。