有没有办法在 DocPad 中包含/渲染来自 `src` 外部的文件？答案

【问题标题】：Is there a way to include/render a file from outside `src` in DocPad?有没有办法在 DocPad 中包含/渲染来自 `src` 外部的文件？
【发布时间】：2014-07-01 12:39:55
【问题描述】：

我有一个项目，在 src 目录之外有很多有用的文档，我想像往常一样呈现 DocPad 文档。

例子：

项目根目录下的文件：README.md、LICENSE、Contributing.md 和类似的文件，它们已经存在并且可以在 GitHub 之类的东西中使用。我想重用这些文件中的内容来创建相应的readme、license 和contributing 页面，或者将这些文件中的内容包含在布局或文档的某处。
我有一个项目，里面有一些文档，我想通过将 package.json 包含在其中将 .md 文件渲染为 DocPad 文档，因此这些文件将在 node_modules在根目录。

在这两种情况下，我想将 src/documents 之外的文件用作部分或文档，并且部分插件似乎无法帮助我（或者我找不到方法让它做我需要的），而@getCollection只能从src/documents获取东西。

所以，问题是：有没有办法告诉 DocPad 处理来自src 文件夹外部的一些文件/文件夹？我错过了什么吗？

如果不是，那么作为插件最好的方法是什么，我应该挖掘哪个方向？

【问题讨论】：

可以在此处找到有关 DocPad 中此功能的源讨论：github.com/docpad/docpad/issues/878

标签： include docpad

【解决方案1】：

DocPad 本身支持将文档存储在默认的src 文件夹之外。这样做的方式是通过DocPad Configuration File 中的documentsPaths 配置选项（例如docpad.coffee）。像这样的：

 path = require('path')
 docpadConfig = {

        documentsPaths: [
            'documents'
            path.resolve('..','data','documents')
        ]
 ....

当然，如果您只想在文件系统的某个位置包含任意的单个文件，这将失败。在这种情况下，符号链接将是可行的方法。

【讨论】：

【解决方案2】：

模板助手也可以用于此，因为它们可以做任何你想做的事情。

例如，Bevry Learning Centre 网站使用模板助手通过相对路径渲染任意文件作为代码示例：

模板助手：https://github.com/bevry/learn/blob/6e202638f2321eec2633d1dbeaf1078bdb953562/docpad.coffee#L244-L257
使用模板助手的模板：https://github.com/bevry/documentation/blob/f24901251d19ec1cfa56fcee14c2c6836c0a995c/node/handsonnode/03-server.html.md.eco

如果您还想渲染它们，可以将此类解决方案与Text Plugin 结合使用。

组合应该是这样的：

DocPad 配置文件中的模板助手：

docpadConfig =
    templateData:
        readProjectPath: (relativePath) ->
            fullPath = require('path').join(__dirname, relativePath)
            return @readFullPath(fullPath)
        readRelativePath: (relativePath) ->
            fullPath = @getPath(relativePath)
            return @readFullPath(fullPath)
        readFullPath: (fullPath) ->
            result = require('fs').readFileSync(fullPath)
            if result instanceof Error
                throw result
            else
                return result.toString()

使用Eco作为模板引擎的Text Plugin模板助手的使用：
```
<t render="markdown"><%- @readProjectPath('README.md') %></t>
```

【讨论】：

【解决方案3】：

答案很简单：相对符号链接。 Docpad 可以完美地处理它们。

这样，要在文档中包含 README.md 的符号链接，您应该这样做（使用 src/documents 的 pwd）：

ln -s ../../README.md readme.html.md

或者，如果是来自项目模块之一的文档：

ln -s ../../node_modules/foobar/docs/ docs

这两种变体都能完美运行。

注意：符号链接可能很棘手。请参阅这些以了解一些常见问题：

【讨论】：

很遗憾 DocPad 本身或插件不支持此功能，我需要不强制创建符号链接的解决方案。有人吗？
@ni5ni6 我添加了一个答案，说明如何在没有符号链接的情况下执行此操作。

【解决方案4】：

就像不同答案之间的比较：

当您想要添加整个额外目录以包含在 DocPad 数据库中以被 DocPad 视为正常时，请使用 paths solution。
当您想要包含特定文档或文件时使用sym/hard link solution，您希望将其视为 DocPad 文档或文件，以及所有智能文件解析和文档呈现，包括布局、数据库和缓存功能。
当您想要包含出于任何原因不想包含在 DocPad 数据库中的特定文件时，请使用 template helper solution。

将此答案设为社区 wiki 之一，因此可以相应更新以获得新答案和更好的详细信息。

【讨论】：