coffeescriptweb-hostingdocpad

Practical way to use DocPad for a site with multiple landing pages


I would like to use DocPad together with its built-in server.

For a website with a single landing page I have set up the structure as recommended on DocPad website: all page sources go into the src/documents, static files into src/files and layouts for the page sources into src/layouts. Then docpad run will generate the resulting site in the out directory and launch a web server using which I can inspect the current state in my browser.

Now, I would like to do the same with multiple landing pages. That means, I plan to deploy files to one site, http://site-one.org and other files to another site http://site-two.org. I am doing this by deploying web pages to two distinct directories /public/site-one/ and /public/site-two/ at my web hoster.

What is the most practical way to accomplish this with DocPad?

These are the things I have tried so far -- they both work (sort of), but neither is very elegant:

  1. Let page sources go into src/documents/site-one and src/documents/site-two and static files into src/files/site-one and src/files/site-two. This renders the entire site properly and it can be uploaded easily. However, the entire DocPad infrastructure with live-reload and the built-in server no longer works (since the built-in server root directory points to out/ instead of out/site-[one|two]/ as it should).
  2. Have two separate DocPad-installations with duplicate docpad.coffee files, duplicate plugins and partially duplicate src/* trees and then upload the resulting out tree to the corresponding sub-directory on the server.

Update: When using option 1, instead of using DocPad built-in live-reload feature it's possible to use one's own web server, point it to out/site-one on one port and out/site-two on another port and then use the grunt live-reload feature which is part of grunt-contrib-watch, where grunt is available as a plugin here. It requires adding a single line of code to the template file, see this link, and to configure the plugin, see this link.

Update 2: A possible solution would involve the ability to set a custom directory for the server. By default it is set to the out directory. While that can be changed, it is not possible to specify separate directories for the generate action and the watch action. However, I have not found such an option in the configuration files.


Solution

  • Turns out that this is much easier than I thought. DocPad has a scarcely documented feature called "environments". This allows to customize several of the regular configuration variables, making it easy to pick the desired landing page on the command line.

    This blog post on multiple languages demonstrates exactly how to customize both the document and the output paths in different environments. Applied to my original problem it becomes:

    docpadConfig = {
        ...
        environments:
            site-one:
                documentsPaths: ['documents_site-one']
                outPath: 'out_site-one'
            site-two:
                documentsPaths: ['documents_site-two']
                outPath: 'out_site-two'
        ...
    }
    

    Then it is as simple as

    docpad [generate|run|...] --env [site-one|site-two|...]
    

    to run regular commands like generate etc. for one of the landing pages by picking the proper custom environment.