Question

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

示例：

项目根目录下的文件：README.md，LICENSE，Contributing.md和类似的文件已存在，可用于GitHub等内容。我想重用这些文件中的内容来创建相应的readme，license和contributing页面，或者将这些文件中的内容包含在布局或文档中。
我有一个项目里面有一些文档，我想通过将.md文件包含在package.json中来将其作为DocPad文档呈现，所以这些文件将在node_modules根目录。

在这两种情况下，src/documents之外的文件都是我想用作部分或文档的，而且似乎部分插件无法帮助我（或者我无法使用找到一种方法让它做我想做的事情，而@getCollection只能从src/documents获取内容。

所以，问题是：有没有办法告诉DocPad处理src文件夹外部的一些文件/文件夹？我想念一下吗？

如果没有，那么作为插件的最佳方式是什么？我应该挖掘哪个方向？

Answer 1

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

 path = require('path')
 docpadConfig = {

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

当然，如果你想在文件系统的某个地方包含任意的单个文件，那么这将会失败。在这种情况下，符号链接将是最佳选择。

Answer 2

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

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

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

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

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

这两种变体都能很好地运作。

注意：符号链接可能很棘手。有关常见问题，请参阅以下内容：

Answer 3

也可以使用模板助手，因为他们可以做任何你想做的事。

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

模板助手：https://github.com/bevry/learn/blob/6e202638f2321eec2633d1dbeaf1078bdb953562/docpad.coffee#L244-L257
使用模板助手Tempalte：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作为模板引擎使用模板助手和文本插件：

<t render="markdown"><%- @readProjectPath('README.md') %></t>

Answer 4

正如不同答案之间的比较：

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

将此答案作为社区维基的答案，因此可以相应更新以获得新的答案和更好的细节。

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

4 个答案: