Sometimes things go bad, and you need to get into DocPad and work out what's happening. Perhaps a plugin isn't working as expected, or content isn't being generated—or, you're just curious as to how to do it.

And to do that, you'll need to get your debugging on.

What you'll need

  1. Get a Webkit based browser (both Google Chrome and Safari work great)

Debugging with Node Inspector

  1. Install Node Inspector with the following

    npm install -g node-inspector
  2. Run Node Inspector in that terminal window

  3. In another terminal window, run the local DocPad installation in debug mode:

    ./node_modules/docpad/bin/docpad-debug run
  4. Navigate to in your Blink-based browser (i.e. Google Chrome) and start debugging

    1. Sometimes you may have to refresh or restart the Node Inspector or DocPad instances. This is unfortunate, but normal.

    2. It may break on the first line of docpad.js file any not reflect this in the view, in that case play through it a few times (by clicking the next button a few times) in order to refresh the view. This is unfortunate, but normal.

Debugging with TraceGL

  1. Follow the instructions on the TraceGL ReadMe

  2. Download it to somewhere in your PATH, and run the following on it:

    mv tracegl.js tracegl
    chmod +x tracegl
  3. Run TraceGL on DocPad

    docpad-trace run
  4. Follow the outputted instructions

  1. Add your NODETIME API key to your environment. We recommend the following method:

    printf "\n\n# NodeTime API Key\nexport NODETIME_KEY='YOUR_KEY'" >> ~/.bash_profile
  2. Run DocPad with the --profile flag, so:

    docpad --profile run
  3. Follow the outputted instructions

Profiling with Node Webkit Agent

  1. Run DocPad with the --profile flag, so:

    docpad --profile run
  2. Run kill -SIGUSR2 123 with 123 being whatever the outputted process id is