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
  • Does it work on Windows?
  • What is markup?
  • What is a templating engine?
  • What is a layout?
  • What is a document's meta information/data?
  • Is a document aware of its meta data?
  • What do the extensions mean?
  • What is findAllLive?
  • Which one should I use and when?
  • How can I learn more about the NoSQL queries available and the internals of Query-Engine?
  • How do I hide a document from being rendered (e.g., a draft post)?
  • How do I re-render a document on each request (e.g., dynamic documents)?
  • What are render passes?
  • How do I create custom 404 and 500 pages?
  • What data is exposed to my template engine?
  • How can I use environment variables in DocPad?
  • How do I disable certain plugins?
  • How do I only enable the plugins that I actually use?
  • How do I customise the configuration sent to a plugin?
  • Where can I host my DocPad website?
  • How can I get Jade to render other DocPad supported markups?
  • How can I get my templating engine to render other DocPad supported markups?
  • How can I re-use particular templates again and again throughout my site?
  • How do I make DocPad detect file changes faster?
  • Cannot get past accepting the Terms of Service
  • When installing I see a lot about ./cyclic.js, what is this?
  • Want more help?

Was this helpful?

  1. Start

FAQ

PreviousDeployNextTroubleshoot

Last updated 5 years ago

Was this helpful?

Does it work on Windows?

Sure does.

What is markup?

Whenever we write something we're using markup. It's merely a way of formatting content. For instance, if we are writing a .txt file in Notepad, we will be using plain-text as the markup. But say we want to get more advanced, and add things like bold text or italic text to our content, then we could use a markup like Microsoft Word (.doc), Rich Text Format (.rtf) or simply Markdown (.md) or HTML (.html). These markups allow us to express our content with rich formatting.

For instance, bold in Markdown is **bold**, where in HTML it is <strong>bold</strong>. The markup that you choose for your content is highly dependent on what content you'd like to write. If you're mostly dealing with structural data (like a page layout) then HTML, Jade, Haml, or CoffeeKup would be a good way to go. If you're mostly dealing with textual data (like a blog post) then Markdown would probably the way to go.

DocPad supports unlimited markups thanks to its plugin system. It doesn't believe in a one size fits all, but in always using the best tool for a job. It's easy to learn new markups, there may be a bit of a learning curve, but you'll quickly adjust, be empowered, and grateful that you now have a new tool under your belt.

DocPad currently only supports rendering plain-text formats, meaning that rendering binary formats like img to jpg or binary-text formats like doc to rtf (they're not plain-text formats like txt, docx, or xml but in fact binary formats) does not currently work.

What is a templating engine?

Often at times we will write documents which start seeming a bit repetitive, or we would like to add a bit of dynamicness to our document. Templating engines allow us to do this, as they allow for the insertion of logic into our chosen markup.

For instance, if I wanted to display a random number I could do the following:

  • : <%= Math.random() %>

  • : = Math.random()

  • : = Math.random()

This is pretty useful, as we can also do things like loops, or assign certain pages or parts of our layout into new files and use them again and again whenever we need them, instead of having to manually duplicate content. This is what empowers us to be able to use Layouts - discussed next.

What is a layout?

Layouts wrap around our documents. They are generally the most generic and re-used part of an entire website, or book for that matter. They contain generally the layout of the page, including the structural information and the meta information (used for search engines, etc.).

What is a document's meta information/data?

At the start of each document is an optional area right up the top that looks something like this

---
title: "My awesome blog post"
---

That is your document's meta data. It won't be included in the output of the document. You can use it to assign extra data to your document (such as title, date, tags, etc.).

Is a document aware of its meta data?

It sure is!

If you're using Eco as the rendering engine, you can totally do this:

---
title: My awesome blog post
meaningOfLife: 42
---

What is the meaning of life? <%= @document.meaningOfLife %>

To use Eco, simply ensure that you have the extension .eco at the end of your file (e.g., my-blog-post.html.eco). It doesn't have to be at the end, but it mustn't be the first extension (as the first extension is what you are rendering to).

What do the extensions mean?

The extensions .html.eco means process this with Eco and render it as HTML. Alternatively, we can get pretty inventive and do something like this: .html.md.eco which means process this with Eco, then Markdown and finally render it as HTML.

What is findAllLive?

There are two methods that Query-Engine provides for querying Backbone Collections. The first is findAll and the second is findAllLive.

findAll does a once-off scan of all the models in the collection that matches the criteria and returns the result in a new Backbone Collection, pretty standard stuff.

findAllLive creates a new child collection with the original collection as the parent, the new child collection then listens to the change events of the parent, and will automatically test the changes against the child collection's criteria. This is incredibly efficient for long running collections, where data changes over time.

Never use findAllLive for short-lived collections (especially in your templates). It will cause more and more and more child collections and listeners to be created and added, causing a memory leak and unexpected results.

Which one should I use and when?

Use findAll when you are needing once-off/short-living collections. Typical use cases are inside your templates or inside other events within your plugin.

How can I learn more about the NoSQL queries available and the internals of Query-Engine?

How do I hide a document from being rendered (e.g., a draft post)?

How do I re-render a document on each request (e.g., dynamic documents)?

What are render passes?

Rendering is a multi-step process. First we render everything that is a standalone document (i.e. documents that don't include anything else). Once that is done, we then render all documents that include other documents. This is useful, as we can first render blog posts, then render the content listings second.

At times, you may have multiple levels of cross document references. For instance if document a references document B which references document C. In this case you would want to up the renderPasses configuration option for each amount of cross document references you have.

How do I create custom 404 and 500 pages?

Add a src/render/404.html for 404 pages, and src/render/500.html for 500 pages. If you create a dynamic page (adding the dynamic: true meta data header) your templating engine (e.g., 404.html.eco) will also get access to req (the request instance), res (the response instance), err (the error that occurred - for 500 errors pages only, not for 404 error pages). Allowing you to do something like this for src/render/500.html.md.eco:

---
layout: default
title: "An internal error occured - 500"
dynamic: true
---

## An error occured on <%= @req.url %>: <%= @err.message %>

What data is exposed to my template engine?

For instance, to output the current document's title with Eco, you would use: <%=@document.title%>. The reason for the @ is because Eco associates the templateData to the current scope, which with CoffeeScript (what Eco uses) you access by using the @ character.

How can I use environment variables in DocPad?

To quickly override existing environment variables for a single invocation of DocPad, specify it on the command line before the docpad command:

$ API_URL=localhost:1234 docpad run

How do I disable certain plugins?

How do I only enable the plugins that I actually use?

How do I customise the configuration sent to a plugin?

Where can I host my DocPad website?

How can I get Jade to render other DocPad supported markups?

How can I get my templating engine to render other DocPad supported markups?

How can I re-use particular templates again and again throughout my site?

How do I make DocPad detect file changes faster?

Cannot get past accepting the Terms of Service

TL;DR start DocPad with the --offline option and see if that works. :)

When installing I see a lot about ./cyclic.js, what is this?

If simply installing DocPad, this is not something to worry about. npm still outputs this, although it's not actually doing anything.

So it is normal, don't worry about it. :)

Want more help?

DocPad's querying capabilities are provided by a project called which adds support for NoSQL queries to JavaScript Objects and Backbone Collections. In DocPad's case, we use Backbone for our Models, so we enhance our collections with Query-Engine to gain NoSQL querying for them.

Use findAllLive when defining long-running custom collections. Typical use cases are via the collections property of your , or via the within your plugin.

However, ideally wherever possible you should try to use DocPad's built-in or for querying as these methods are highly optimised for DocPad, whereas the low-level Query-Engine methods are not.

Check out the ignored .

Check out the dynamic .

Templating engines are renderers for languages which support business logic. For instance, the template engine provides us with the following syntax <% your business logic %> or to output a variable we can use <%=some variable%>.

As such, the data which we expose to our templating engines is called the templateData.

All environment variables are automatically available in Node applications through . DocPad also loads variables from a special .

Check out the enabledPlugins .

Check out the enableUnlistedPlugins .

Check out the plugins .

Check this , see if it helps. :)

Check this for a conversation on this bug.

Install it now.
We will be addressing this in a future release of DocPad.
Eco
Jade
Haml
Query-Engine
Take a look at the Guide to Using Query-Engine
meta data property
meta data property
Eco
Check out the full listing of template data & helpers here.
configuration property
configuration property
configuration property
Check out our deployment section here.
Check out the usage section on the Jade Plugin.
Check out the text plugin.
Check out the partials plugin.
GitHub issue
GitHub issue
Visit our support page.
docpad configuration file
APIs
process.env
extendCollections event
template helpers
environment file