CODEWITHSUNDEEP
includedocpad
kizu
kizu

Reputation: 43224

Is there a way to include/render a file from outside `src` in DocPad?

I have a project which have a lot of useful docs outside of the src directory which I'd like to render as usual DocPad documents.

Examples:

In both those cases there are files outside of the src/documents that I'd like to use as partials or documents, and it seems that the partial plugin can't help me (or I couldn't find a way to make it do what I need), and the @getCollection can only get things from the src/documents.

So, the question is: Is there a way I can tell DocPad to treat some of the files/folders from the outside of the src folder? Do I miss something?

If not, then what would be the best way to do it as a plugin, which direction should I dig?

Upvotes: 1

Views: 246

Answers (4)

kizu
kizu

Reputation: 43224

The answer would be a rather simple one: relative symbolic links. Docpad handles them perfectly.

This way, to have a symlink of README.md inside your documents, you should do this (with pwd of src/documents):

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

Or, in case of a docs from inside one of the project's modules:

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

Both those variants work perfectly.

Note: Symlinks can be tricky. Refer to these for some common gotchas:

Upvotes: 1

Steve Mc
Steve Mc

Reputation: 3441

DocPad natively supports storing documents outside of the default src folder. The way you do this is via the documentsPaths config option in the DocPad Configuration File (e.g. docpad.coffee). Something like this:

 path = require('path')
 docpadConfig = {

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

Of course, where this will fall down is if you want to just include arbitrary, individual files somewhere on the file system. In such cases symlinks would be the way to go.

Upvotes: 2

balupton
balupton

Reputation: 48650

Just as a comparison between the different answers:

  • Use the paths solution when you want to add entire extra directories to be included inside the DocPad database to be treated as normal by DocPad.

  • Use the sym/hard link solution when you want to include specific documents or files that you would like to be treated as a DocPad document or file, with all the intelligent file parsing and document rendering, including layout, database, and caching features.

  • Use the template helper solution when you want to include specific files that you do not want included in the DocPad database for whatever reason.

Made this answer a community wiki one, so it can be updated accordingly for new answers and better details.

Upvotes: 0

balupton
balupton

Reputation: 48650

Template helpers can also be used for this, as they can do whatever you want.

For instance, the Bevry Learning Centre website uses template helpers to render arbitrary files by relative paths as code examples:

  1. Template Helper: https://github.com/bevry/learn/blob/6e202638f2321eec2633d1dbeaf1078bdb953562/docpad.coffee#L244-L257
  2. Tempalte using the Template Helper: https://github.com/bevry/documentation/blob/f24901251d19ec1cfa56fcee14c2c6836c0a995c/node/handsonnode/03-server.html.md.eco

If you would also like to render them, you could combine such a solution with the Text Plugin.

The combination would be like so:

  1. Template Helper in DocPad Configuration File:

    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()

  2. Usage of Template Helper with Text Plugin using Eco as templating engine:

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

Upvotes: 1

Related Questions