Search code examples
includedocpad

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:

  • Files at the root of the project: README.md, LICENSE, Contributing.md and similar, which are already there and can be used in things like GitHub. I would like to reuse the content from those files to create the corresponding readme, license and contributing pages, or to include the contents from those files somewhere in layout or a document.

  • I have a project that have some docs inside, and I'd like to render the .md files as DocPad documents from it by including it in package.json, so those files would be in node_modules at root.

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?

Solution

  • 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: