DocPad
  • DocPad
  • Start
    • Install
    • Overview
    • Beginners Guide
    • Deploy
    • FAQ
    • Troubleshoot
    • Support
    • Upgrade
    • Performance
  • Core
    • API
    • Command Line Interface
    • Configuration
    • Events
    • Meta Data
    • Sequence Flow
    • Template Data & Helpers
  • Extend
    • Extending
    • Write a Plugin
  • Community
    • Contribute
    • Participate
    • Plugins
    • Showcase
    • Roadmap
Powered by GitBook
On this page
  • Known Issues
  • Need more help?

Was this helpful?

  1. Start

Troubleshoot

PreviousFAQNextSupport

Last updated 5 years ago

Was this helpful?

Known Issues

Regressions we're working on

The following are issues the DocPad team are aware of and will fix shortly:

  • Dynamic pages are behaving weirdly:

  • Ignored documents are showing up in collections and being served:

It just hangs after accepting the TOS or subscribing to the newsletter

It seems that this is associated to being behind a firewall or a proxy. You can apply .

I got "npm ERR! Failed to parse json"

Check your project's package.json file with , to ensure it does not contain any errors, such as missing semicolons, quotes or commas.

I am getting permission errors after I install things

Chances are this isn't a problem within DocPad, but rather one of your Node/NPM installations. Run the following in Terminal, once done, try your original action again:

sudo chown -R $USER /usr/local ~/.npm
chmod -R 755 ~/.npm

Be sure that your tmp dir is writable for the current user:

sudo chown -R $USER:$GROUPS ~/tmp

If that fails, we'd recommend re-Installing Node.js with Bevry's .

When I run npm install on windows, I get gyp ERR! configure error

  • For Windows XP/Vista/7 installations:

  • For 64-bit builds of Node.js and native modules, you'll also need:

      • If the install fails, try uninstalling any C++ 2010 x64&x86 Redistributable that you have installed first.

  • If you get errors that the 64-bit compilers are not installed, you may also need:

  • For Windows 7/8:

When I run docpad run on Windows, it asks me what program I would like to open the file in

Watching doesn't work; works only some of the time; I get EISDIR errors

File watching is a pretty timid thing. We're currently working on making it better. There are currently two methods for watching files: watch and watchFile. The default is watch, and it uses the operating system's watching mechanisms. However, sometimes those mechanisms aren't the best. If that's the case, we'd like to switch our watching method to watchFile. It's slower, but it works when watch doesn't.

watchOptions: preferredMethods: ['watchFile','watch']

Mac OS X users are most likely to encounter this issue.

Watching is very slow to notice changes

regenerateDelay: 0
watchOptions: catchupDelay: 0

Error: "We couldn't find an existing DocPad project inside your current directory..."

Error: "Could not locate git binary"

  • Reinstall git and make sure to select the option during installation that asks if you would like to add it to your PATH variable (may also be called, would you like git to be available to the command line)

  • Manually add the location your git binary resides in to your PATH variable

Error: "EMFILE, too many open files"

As Node.js is like an octopus, able to do many things at the same time, sometimes Node.js will always try to do too many things than the operating system will let it. In which case, you can increase the amount of files allowed at the same time by running ulimit -n 8192 in your terminal.

How can I make DocPad go even faster?

There are a few things you can do:

  • Use native/JavaScript implementations of renderers instead of non-native, non-JavaScript ones

    • (e.g., instead of using SASS, use nodesass, Stylus, or Less)

I upgraded, and it doesn't work

Whenever I output a variable (like content) it is escaped (< rendered as &lt;)?

Template engines by default escape all variable output. Escaping is when we turn things like the open bracket < into its html entity equivalent &lt;. This helps prevent malicious code accidentally being injected into your website which can open the door to XSS attacks. As such, we have to use a special syntax to keep the variable unescaped when outputted. The special syntax is different for the templating engine your using, so here are the ways we know:

  • Eco: <%- content %> instead of <%= content %>

  • Jade: != content instead of = content

  • Haml: != content instead of = content

The output of a variable (like document.title) is empty or null

Be sure that you use the correct syntax for your template language. Refer to the documentation of your chosen language. For example: When you want to put the output of a variable into the content of an (HTML) element in Jade, you must not write a whitespace between the element and the =. So this is wrong: title = document.title and that is correct: title= document.title

I get a whole bunch of npm / missing module/package / installation failed errors

Once that's done, try whatever you were doing again. You may need to run rm -Rf node_modules; npm install as well.

Once it's all working, then you're free to resume Dropbox syncing.

The Growl notifications aren't displaying

The exception raised by the Jade plug-in during documents generation makes no sense

The Jade compiler uses the full file content on the disk to show where the parsing error is. But since Docpad strips the meta header before submitting the data to the Jade compiler, you must add the number of lines of this header to get the right error spot in your code.

Need more help?

Recommended

It turns out that Windows will prefer to treat the local docpad.js file as the executable versus the global docpad.cmd file. To get around this, type docpad.cmd run instead in projects that have a docpad.js file.

To do this, add the following to your :

Add the following to your :

This will introduce problems however if you have previously customised watchOptions, or if your editor uses swapfiles.

This occurs when you run docpad run inside a directory that already has existing files, but doesn't have a structure that resembles a DocPad project. We can't directly ask you if you would like to use an existing for the basis of your new website, as pulling in a skeleton inside a non-empty directory may overwrite your existing files. If would like to still use a skeleton for the basis of your new website, you will have to run DocPad inside a new empty directory. If you would like to start your website from scratch (not use an existing skeleton) then you can follow the guide. Hope that helps :) .

This happens when the installation is not exposed to your . You can solve this in either of these two ways:

If you are using (an online syncing and backup tool) and your project is inside your Dropbox folder, then click the Dropbox menu icon and select "Pause Syncing".

If you're still experiencing issues, then be sure to post about it on the .

This means you need to from the . This package provides a command line application for calling Growl, which can then be used by DocPad.

https://github.com/bevry/docpad/issues/767
https://github.com/bevry/docpad/issues/807
this workaround
JSONLint
recommended installation instructions
Python
v2.7.8
Microsoft Visual Studio C++ 2010
Windows 7 64-bit SDK
compiler update for the Windows SDK 7.1
Microsoft Visual Studio C++ 2012 for Windows Desktop
More information here.
DocPad configuration file
DocPad configuration file
More info here.
git
PATH variable
More information about this here.
Move files that you do not reference in content listings to a raw directory with the raw plugin
Set standalone: true to the meta data of documents that you regenerate often
Help us implement performance optimisations
Check out the Upgrade Guides here
Dropbox
issue tracker
download and install the growlnotify extra
Growl website
Visit our support page.
Getting Started
If you need more help then check out our Support Channels
skeleton