foliantcontrib.includes 1.1.6

包括用于叶子的

includes preprocessor允许您重用叶状项目源中其他文档的部分。它可以包含本地计算机和远程git存储库中的文件。您可以包括整个文档以及特定标题之间的部分，在途中删除或规范化包含的标题。

安装

$ pip install foliantcontrib.includes

配置

要使用默认选项启用预处理器，请将includes添加到项目配置中的预处理器部分：

preprocessors:-includes

预处理器有许多选项：

preprocessors:-includes:cache_dir:!path.includescacherecursive:truealiases:...

缓存目录 ：克隆git存储库的目录路径。它可以是相对于项目路径的路径，也可以是全局路径；您可以使用~/快捷方式。

>    **Note**
>
>    To include files from remote repositories, the preprocessor clones them. To save time during build, cloned repositories are stored and reused in future builds.

递归 ：定义是否应处理包含在包含文档中的内容的标志。

别名 ：从别名映射到Git存储库URL。一旦在这里定义了别名，就可以使用它来引用存储库，而不是它的完整url。

>    **Note**
>
>    Aliases are available only within the legacy syntax of include statements (see below).

For example, if you set this alias in the config:

    - includes:
        aliases:
            foo: https://github.com/boo/bar.git
            baz: https://github.com/foo/far.git#develop

you can include the content of `doc.md` files from these repositories using the following syntax:

    <<include>$foo$path/to/doc.md</include>

    <<include>$baz#master$path/to/doc.md</include> 

Note that in the second example the default revision (`develop`) will be overridden with the custom one (`master`).

用法

预处理器允许include语句有两种语法变体。

传统语法更简单、更简短，但灵活性较差。目前还没有扩展的计划。

版本1.1.0中引入的新语法更加严格和灵活。它更适合于复杂的情况，并且在将来很容易扩展。这是首选语法。

两种语法变体都使用<；<；include>；..<；/include>；标记。

如果包含的文件是在标记之间指定的，则是传统语法。如果在标记属性（src，repo-url，path）中引用了该文件，则为新文件。

新语法

若要强制使用新的语法规则，请在<；<；include>；…<；include>；标记之间不放置任何内容，并在标记属性中指定本地文件或远程Git存储库中的文件。

要包含本地文件，请使用src属性：

Text below is taken from another document.

<<include src="path/to/another/document.md"></include>

要包含来自远程git存储库的文件，请使用repo-url和path属性：

Text below is taken from a remote repository.

<<include repo_url="https://github.com/foo/bar.git" path="path/to/doc.md"></include>

您必须在repo url属性中指定完整的远程存储库url，此处不支持别名。

可选的分支或修订可以在修订属性中指定：

Text below is taken from a remote repository on branch develop.

<<include repo_url="https://github.com/foo/bar.git" revision="develop" path="path/to/doc.md"></include>

属性

src ：要包含的本地文件的路径。

回购URL ：没有修订的完整远程Git存储库URL。

路径 ：远程Git存储库中文件的路径。

>    **Note**
>
>    If you are using the new syntax, the `src` attribute is required to include a local file, and the `repo_url` and `path` attributes are required to include a file from a remote Git repository. All other attributes are optional.

>    **Note**
>
>    Foliant 1.0.9 supports the processing of attribute values as YAML. You can precede the values of attributes by the `!path`, `!project_path`, and `!rel_path` modifiers (i.e. YAML tags). These modifiers can be useful in the `src`, `path`, and `project_root` attributes.

修订版 ：git存储库的修订版。

来自u标题 ：当需要包含引用文件内容的某些部分时，开始标题的全部内容。

到u标题 ：当需要包含引用文件内容的某些部分时，结束标题的全部内容。

来自ID ：当需要包含引用文件内容的某些部分时，起始标题或起始锚点的ID。from_id属性的优先级高于from_heading

到'u id ：当需要包含引用文件内容的某些部分时，结束标题或结束锚点的ID。to_id属性的优先级高于to_heading

结束 ：指示预处理器剪切到包含内容结尾的标志。否则，如果指定了from_heading或from_id，则预处理器会将包含的内容剪切到与起始标题相同级别的下一个标题或起始锚之前的标题。

$ pip install foliantcontrib.includes

$ pip install foliantcontrib.includes

$ pip install foliantcontrib.includes

$ pip install foliantcontrib.includes

$ pip install foliantcontrib.includes

$ pip install foliantcontrib.includes

$ pip install foliantcontrib.includes

$ pip install foliantcontrib.includes

$ pip install foliantcontrib.includes

$ pip install foliantcontrib.includes

preprocessors:-includes