# DocPad DocPad rethought web development and was the first big static site generator for Node.js gaining over 2000 stars, hundreds of daily users, 200 plugins, and 100 contributors. {% embed url="" %} Watch the talk that launched DocPad into publicity {% endembed %} {% hint style="info" %} DocPad lead the static-site-generator wave throughout 2011 until 2014, and I am proud of my investment's accomplishments during that time. However despite lingering users and a dark age of prolonged unpaid maintenance, these days it should be considered archived for the history books. It could not keep up with the competitive landscape in a way that provided return for investment, especially when considering the sunken ship of opportunity cost of the time that was invested into it. DocPad's final releases were devoted to wrap up the project with a nice bow, and to admit its mistakes. Something which in hindsight, was also a mistake — an abrupt end would have been a better investment of time — unfortunately my conscience required closure to move on. These are the summaries of DocPad's final hurrah: * [v6.79](https://github.com/docpad/docpad/blob/master/HISTORY.md#v6794-2017-march-31) was the last release to support legacy plugins * [v6.80](https://github.com/docpad/docpad/blob/master/HISTORY.md#v6800-beta-2018-march-7) incorporated many years of ecosystem upgrades, increased performance, solved many long-standing issues, removed all non-vital server communication, and dropped support for legacy plugins * [v6.81](https://github.com/docpad/docpad/blob/master/HISTORY.md#v6810-2018-august-21) removed the dynamic abilities from DocPad which was an innovative feature of DocPad at the time but it grew to become better served by newer tooling such as Next and Nuxt * [v6.82](https://github.com/docpad/docpad/blob/master/HISTORY.md#v6820-2018-september-7) made many refinements and fixed many long-standing issues * [v6.83](https://github.com/docpad/docpad/blob/master/HISTORY.md#v6830-2020-august-5) removed the last cloud code, and updated the Bevry packages for massive peformance improvements These days you are better served by either: * The [un-staticsitegenerators](https://github.com/bcomnes/bret.io/blob/3bf02ba6572cc6ff9919ab3de95a03e5dcb7dfdc/package.json#L6-L28) concept, which is using a collection of independent [unix-style](https://en.wikipedia.org/wiki/Unix_philosophy#Do_One_Thing_and_Do_It_Well) commands composed into a completely customisable and interchangeable build system with only 20 lines of code. * Frameworks like [Sapper](https://sapper.svelte.dev/), [Stencil](https://next.stenciljs.com/), [Next](https://nextjs.org/), [Nuxt](https://nuxtjs.org/). * Whatever tools that [Headless Content Management Systems](https://alternativeto.net/tag/content-as-a-service/) integrate with. * Personally, I find [lit-html's](https://lit-html.polymer-project.org) [ecosystem](https://github.com/web-padawan/awesome-lit-html) promising. For those wanting to write their own static site generators, [here are my learnings](https://medium.com/ephemeral-living/2017s-generation-of-static-site-generators-164c3b7b9f97). For those wanting to avoid the same time investment mistake, please read [Zero to One](https://www.goodreads.com/book/show/18050143-zero-to-one) — if that book existed earlier, it would have saved me a decade of my life. With that said, the documentation continues for your lingering curiosity. DocPad should still work, but if it doesn't, you're on your own. Please submit fixes to the documentation if needed. Regards,\ [Benjamin Lupton](https://balupton.com), Creator of DocPad {% endhint %} ## What is DocPad? DocPad takes files on your computer, such as easy to read markdown documents, and then transforms them into static output that can be deployed anywhere. ### Problems with Traditional Web Architectures Despite all the amazing wonder of current web application architectures, they're mostly: * **Inherently slow** * Usually built on blocking, live-then-die platforms * Performance is an afterthought, re-render every single time (by default, caching can be enabled to improve this) * **Bloated** * Huge, include-everything codebase, with little or no code re-use (especially between frameworks) * Overkill for everything, as no single project will use every feature of the CMS * **Complex** * Gigantic learning curves, usually measured in months (instead of days or hours) * You require CMS/framework developers instead of web developers * **Difficult** * Setting up a new website is time-consuming and complex * Uh oh! "database not installed" or "version invalid" * Migrations and deployments are a royal pain in the ass * **Limited** * WYSIWYG editors are sucky and stupid - why re-invent the wheel? We're already trained with and love our desktop counterparts (Sublime Text, Vim, Byword, etc.) * Abstractions on the go? Forget it - you're boxed in, unless you've got a machete * Want to use your own pre-processors, markups, and templating engines? Tough: they're handled by the core. ### DocPad, an intuitive static-site generator On the other hand, let's compare that with DocPad, which is: * **Website inherently fast** * Built on a non-blocking, stay-alive platform * Performance from the ground up, re-render only when changes occur (by default, can be configured differently) * **Lightweight** * Tiny core, with anything that's re-usable abstracted out into modules that other systems can use * All non-essential core functionality lives in opt-in plugins * **Simple** * Tiny learning curve; get started in minutes, become a pro in days * Web developers already have everything they need to get started * **Easy** * Setting up a new website can be done in minutes * In-memory database provides querying without the need for a manual installation * Migrations and deployments are handled via Git, the tool we are used to * **Robust** * Use your desktop counterparts to edit content naturally (Sublime Text, Vim, Byword, etc.) * Abstraction friendly; code the way you want, how you want * Use whatever language, pre-processor, markup, templating engine you want - it's all covered via our [opt-in plugins](/community/plugins) (and if it isn't, it's very easy to add) Besides this, thanks to the opt-in modular philosophy of Node, we benefit from all the innovations of the community as a whole, including: * [Socket.io](http://socket.io) for realtime communication between the server and client-side * [Browserify](https://github.com/substack/node-browserify) for being able to share server-side code directly with the client-side * Native pre-processor rendering such as [CoffeeScript](http://coffeescript.org), [CoffeeKup](http://coffeekup.org), [Stylus](http://learnboost.github.com/stylus/), [LessCSS](http://lesscss.org), etc. So as the Node community grows and innovates, so do we. Awesome. ### Comparison Table For those who like tables, here's the above in table form: |


Feature

| Usual CMS | Usual Static Site Generator | DocPad | | ------------------------------------------------------------------- | ------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------ | | Talent requirements | CMS developer | Backend+frontend developer | Frontend developer | | Developers proficient in | Months | **Days** | **Days** | | Plugin and extension system | **Yes** | No | [**Yes**](/extend/extend) | | Asset pipeline | No | Implicit & bundled | [**Explicit & extendable**](/start/overview) | | Markup languages (markdown, rst, etc.) | No | 1 bundled | **Via** [**plugins**](/community/plugins) | | Pre-processors (sass, less, etc.) | No | No | **Via** [**plugins**](/community/plugins) | | Template engines (eco, jade, etc.) | No | 1 bundled | **Via** [**plugins**](/community/plugins) | | Database querying | **Yes** | No | **Via** [**Query-Engine**](https://github.com/bevry/query-engine) | | Layouts | **Yes** | **Yes** | **Yes** | | Static website output | No | **Yes** | **Yes** | | Re-render each request | Always | No | [**Deprecated**](https://discuss.bevry.me/t/deprecating-in-memory-docpad-importers-exporters/591?u=balupton) | | Extend the web server | **Yes** | No | **Via** [**events**](/core/events) **and** [**API**](/core/api) | | Watching | **N/A** | **Yes** | **Yes** | | Differential regenerations | **N/A** | No | **Yes** | | Live-reload | No | No | **Via** [**`livereload` plugin**](https://github.com/docpad/docpad-plugin-livereload/) | | Partials | No | No | **Via** [**`partials` plugin**](https://github.com/docpad/docpad-plugin-partials/) | | Manual database installation required | Yes | **No** | **No** | | Import pages from file system | No | **Yes** | **Yes** | | Import pages from external database (MongoDB, MySQL, etc.) | **Yes** | No | [**Deprecated**](https://discuss.bevry.me/t/deprecating-in-memory-docpad-importers-exporters/591?u=balupton) | | Import pages from external services (Tumblr, Dropbox, GitHub, etc.) | No | No | [**Deprecated**](https://discuss.bevry.me/t/deprecating-in-memory-docpad-importers-exporters/591?u=balupton) | | Import data from external services (Atom, XML, JSON, etc.) | No | No | **Via** [**`feedr` plugin**](https://github.com/docpad/docpad-plugin-feedr/) | | WYSIWYG editors | **Yes** | No | [**Deprecated**](https://discuss.bevry.me/t/deprecating-in-memory-docpad-importers-exporters/591?u=balupton) | # Install *If you are upgrading from one major version to another (e.g. DocPad v5 to DocPad v6), be sure to checkout our* [*Upgrade Guide*](/start/upgrade) *for information relating to backwards compatibility breaks.* 1. [Install Node & Other Dependencies](https://learn.bevry.me/node/install) 2. Update [npm](https://docs.npmjs.com) and install DocPad ```bash npm install -g npm npm install -g docpad@latest ``` **Note:** If you encounter permission errors with the above, do not use `sudo`, in our experience using `sudo` with node only creates further issues (regardless of DocPad). Follow our Step 1 instructions for a way to install Node with permissions that never require the use of `sudo`. You can verify DocPad has installed correctly by using `docpad -V` to output DocPad's version number. 3. **When upgrading:** in addition to the above, run `docpad update` inside your project directory to ensure that your local installation of DocPad and its plugins are updated to their latest compatible versions. *If you get any errors, try running DocPad anyway (most installation errors are non fatal and just for debugging purposes). If you do get a fatal error then refer to our* [*Troubleshooting Guide*](/start/troubleshoot) *as there's probably already a working solution. :-)* # Overview ### Standard Project Structure Here is the standard project structure you'll see in DocPad projects: * `my-website/` * `out/` * `source/` * `render/` (also `documents/`, for backwards compatibility) * `static/` (also `files/`, for backwards compatibility) * `layouts/` * `docpad.coffee` * `package.json` #### The `out` Directory This directory contains anything that DocPad generates. Any new files added to the `source` directory will be found here after being rendered and written by DocPad. However any files that are deleted from the `source` directory will not be deleted from the `out`directory by DocPad, you have to delete them manually. So if you remove a file and it's still there remember to delete it manually. ;-) #### The `source` Directory This directory contains your website's source files. It contains your layouts, files to be rendered and be in the output and files that are not to be rendered but will still be in the output. The `source` can have the following folders: * The `layouts` directory * The `render` directory (also `documents`, for backwards compatibility, for backwards compatibility)) * The `static` directory (also `files` The `render` and `documents` directories, and the `static` and `files` directories, are merged; files appearing in either are rendered or copied to the output. However, you should use the former names rather than the latter to conform with the latest naming conventions. **The layouts Directory** Layouts work in a very similar way to files in `render`, in that they are rendered and they support meta data. Unlike the files in `render`, however, they are not output to the `out` directory, as they only exist to wrap files in `render` and other layouts within themselves. Layouts work in a nested fashion, with the desired layout being defined by the `layout` meta data property within the child layout/document. Layouts should include child content, which is done using the `content` [template data](/core/template-data) variable. For instance, the code to use the content variable with the [Eco](https://github.com/sstephenson/eco/) templating engine via the [Eco DocPad plugin](https://github.com/docpad/docpad-plugin-eco) would be `<%- @content %>`. **The render Directory** These are files that we would like to render. Rendering occurs extension to extension in the same way the Ruby on Rails asset pipeline works. This means the document `source/render/hello.ext1.ext2.ext3` is rendered from `ext3` to `ext2`, then from `ext2` to `ext1`, resulting in the file `out/hello.ext1`. More common examples of this are rendering [CoffeeScript](http://coffeescript.org/) to JavaScript with the document `source/render/script.js.coffee` to `out/script.js` or writing a blog post that renders from [Markdown](http://daringfireball.net/projects/markdown/) to HTML with the document `source/render/blog/hello.html.md` to `out/blog/hello.html`. The reason we do not support direct rendering from `script.coffee` to `script.js` is that such a convention would eliminate the ability to combine extension renderings, also because ambiguity between extensions that can be rendered in multiple ways. For instance the `coffee` extension could be rendered using [CoffeeScript](http://coffeescript.org/) to JavaScript or using [CoffeeKup](http://coffeekup.org/) to HTML. However, if you really want to use just a single extension, such a thing is supported by the `renderSingleExtensions` meta property. The other important aspect of files in `render` is that they support meta data. Meta data goes at the top of a document and defines information about that particular document. For instance, its title, date and layout are good examples. Meta data is not restricted to particular values, meaning you can define whatever meta data you want against a document. There are some special meta data properties, however, that perform certain functions (e.g., `layout` is used to specify the layout that should be used to wrap the document). You can find the complete listing of special meta data properties on the [Meta Data page](/core/meta-data). **The static Directory** Files in this folder, like those in `render`, are output to the `out` directory. The difference lies in that they are not rendered and do not support meta data. This is where you should put everything that doesn't need to be rendered or need meta data. For example, images, vendor files, plain stylesheet and JavaScript files, etc. #### The `docpad.coffee` file The `docpad.coffee` file can have several different extensions. It defines DocPad's settings. You can find full documentation on the [Configuration docs page](/core/config). #### The `package.json` File This file is needed for every Node.js application. It defines the dependencies that your application requires, such as the DocPad version that your site is developed with and the plugins you are running. You can learn more about `package.json` files on [this page](https://learn.bevry.me/node/ecosystem) of our [Hands on Node Training](https://learn.bevry.me/node/preface). # Beginners Guide ### Introduction Welcome to the Beginner Guide for DocPad. By the end, you'll have all the knowledge necessary to create amazing powerful websites and applications with DocPad. You won't need any special training, and if you are a web developer then you'll already feel right at home. For this guide we'll create a [blog](http://en.wikipedia.org/wiki/Blog) and explain step-by-step how it's done. A blog is just a listing of posts/articles as well as some pages. Posts are intended to allow regular new content, like status updates, to be published, whereas Pages are more permanent, usually providing general background information. Great, let's get started! Oh, and if you ever get stuck, you have a question or need help, then jump onto any of our [official support channels](/start/support#support-channels) and we'll be right with you. Cheers! Click the headings to proceed to the particular section. ### Creating the Standard Project Structure Before we get hacking away on content, we have to create our project and set it up with [DocPad's standard structure](/start/overview). To do this, we'll run the following: ``` mkdir my-new-website cd my-new-website docpad init docpad install serve docpad run ``` The standard directory structure will be set up by the `init` command. Then we'll install the [serve plugin](https://github.com/docpad/docpad-plugin-serve) so we have a web server to show our generated site. The subsequent `run` command will start the web server on [http://localhost:9778](http://localhost:9778/), watch for changes, and regenerate the website when they occur. This runs in the foreground; you can stop it any time by pressing `CTRL+C`. (For the moment we'll keep it running.) Note that when a new directory structure is set up it may be created with `source/documents` and `source/files` directories, rather than `source/render` and `source/static`. You should remove the `documents` and `files` directories and create `render` and `static`directories in order to follow the new naming conventions. ### Adding the Home Page Let's create our first document; the *Homepage* for our website. Create the document `source/render/index.html` and give it the following content: {% code title="source/render/index.html" %} ```markup Welcome! | My Website

Welcome!

Welcome to My Website!

``` {% endcode %} Once you've saved it, open up [http://localhost:9778](http://localhost:9778/) (or refresh if you already had it open) and you'll notice that DocPad has already regenerated your website and see the page we created rendered inside the browser. Fantastic! At this point, if you're using revision control (such as Git), you may want to add the `out/` directory to the list of files to ignore, since that should never be committed. ### Adding the About Page and a Layout Now that's done, we'll want to add our "About Me" page so that people browsing our website will know who we are. To do this, let's create a new document at `source/render/about.html` and give it the content: {% code title="source/render/about.html" %} ```markup About Me | My Website

About Me

I like long walks on the beach. Plus I rock at DocPad!

``` {% endcode %} Now if we go to , we'll be able to see that page in our browser. Awesome! However, duplicating that layout information inside our *Homepage* and our *About* page is pretty redundant. For instance, if we wanted to change the contents of `` to something else, then we'll have to change it in two places! This is where layouts come in. Layouts wrap around our `render` files, so we can define the surrounding areas of a document only once. Let's move the wrapper stuff of our two `render` files into a new layout located at `source/layouts/default.html.eco`, so that we end up with the following: * 
<html>
  <head>
      <title><%= @document.title %> | My Website</title>
  </head>
  <body>
      <h1><%= @document.title %></h1>
      <%- @content %>
  </body>
  </html>
* 
---
  title: "Welcome!"
  layout: "default"
  isPage: true
  ---
  <p>Welcome to My Website!</p>
* 
---
  title: "About Me"
  layout: "default"
  isPage: true
  ---
  <p>I like long walks on the beach. <strong>Plus I rock at DocPad!</strong></p>
However, if you go to either the *Homepage* or the *About* page on our web server, you'll notice that their content is just the layout, and don't actually contain any of the document content. This is because we haven't installed the templating engine for our layout yet. We've also added a new `isPage` attribute, this is our own custom attribute and has no special meaning in DocPad. However, we will give it special meaning later on when we add our menu listings :) #### Installing the Templating Engine *Templating Engines* allow us to embed abstractions inside our `render` files - which is why we have to use them for layouts, as a layout is an abstraction, an abstraction that wraps around a document and outputs the document's content in a specific way :) For this guide, the templating engine we'll be using is [eco](https://github.com/sstephenson/eco) and is available to us via the [eco plugin](https://github.com/docpad/docpad-plugin-eco). So let's install that now by quitting DocPad (`CTRL+C`), and running: ``` docpad install eco ``` Once installed, if we run DocPad again (`docpad run`) and then go our *Homepage* or *About* page, we'll see that the content actually contains the document content. In other words, it has rendered correctly through our eco templating engine. Woot woot! Now, why did we use `<%=` for the document's title, but `<%-` for the document's content? The reason for this is that `<%=` will escape the data we give it before outputting the data, which allows special characters to be interpreted as normal characters. On the other hand, `<%-` will output without performing any escaping, leaving special characters intact. So, why should we escape some things but not others? Generally, whenever the data we want to output is HTML (e.g., the document's content) we want to output it "as is", without any escaping. On the other hand, if we didn't escape document titles, titles such as `3 is > 2` would end up as `3 is > 2`, which is invalid HTML due to the superfluous closing element character, `>`. Thus, using escaping would result in `3 is > 2`, which uses the [HTML entity code](http://www.ascii.cl/htmlcodes.htm) to represent the special character. This is valid HTML and looks exactly the same to the user :) #### A note on Plugins Even though we have chosen to use the Eco templating engine in this guide, there are plenty of others we could use too! We find Eco is very beginner-friendly, since it's the most like HTML. However, after experimenting with some of the others, you may find you'd like to use them instead. Adding support for a new templating engine, pre-processor, or whatever is as simple as installing the plugin for it. DocPad also supports more than just templating engines, though. We have a whole range of different plugins to do all sorts of things, so be sure to check them out! You can find the full listing of plugins we have on the [Plugins](/community/plugins) page. #### A note on Rendering Now, the reason we can support multiple templating engines is because of the way DocPad renders things, file extension by extension. Thus, by creating the file `default.html.eco`, we can render from `eco` to `html`. Conversely, if we tried `default.eco.html`, we'd be trying to render from `html` to `eco`, which wouldn't actually be very useful or even possible. However, other combinations can be rendered in both directions, such as CoffeeScript to JavaScript and JavaScript to CoffeeScript, provided you have the right plugins installed. You can also mix and match extensions, such as `default.html.md.eco`, which renders from `eco` to `md` (markdown) and then `md` to `html`. This allows you to apply abstractions with eco to your markdown `render` files. Awesome! For now, though, it's way out of our scope, so let's get back on track! #### A note on Meta Data What on earth was with the stuff between the `---` at the top of our `render` files? That stuff is our *meta data*. It is where we can define extra information about our document, such as its title, layout, date, whatever. You are not limited to what you can define here; it's up to you. However, there are some pre-defined properties that serve special purposes (such as layout, which we just used). You can learn more about meta data and all the special properties on our [Meta Data](/core/meta-data) page. ### Adding the Live Reload Plugin and Blocks #### Adding the Live Reload Plugin Sweet, so we're doing well so far! We've got two `render` files, and a layout to abstract them. As we are making changes, it sure would be nice if our browser refreshed the page automatically! We can do this with the [Live Reload Plugin](https://github.com/docpad/docpad-plugin-livereload), so let's install that now: ``` docpad install livereload ``` Once you've restarted DocPad, whenever you make a change to the files, you'll notice the browser still doesn't refresh automatically to show the changes! Why? The reason is that we have to add our *Blocks*. #### Adding the Blocks *Blocks* are a way for plugins and even ourselves to be able to easily add scripts, styles and meta elements to our pages. In the instance of the Live Reload Plugin, it needs the *Script Block* to be able to inject the needed scripts into the page that refresh the browser. So to add the three default blocks to our layout, we'll update our `default.html.eco` layout to become: {% code title="source/layouts/default.html.eco" %} ```markup <%= @document.title %> | My Website <%- @getBlock("meta").toHTML() %> <%- @getBlock("styles").toHTML() %>

<%= @document.title %>

<%- @content %> <%- @getBlock("scripts").toHTML() %> ``` {% endcode %} Saving that, and manually reloading our browser, we'll notice that our page now has the necessary scripts for the Live Reloaded Plugin automatically injected right where the scripts block has been output. Now if we make a change to any of the files, we'll notice the browser will automatically refresh. Amazing! In the next part, we'll work with blocks some more by adding our assets to them. ### Adding Assets It's time to start adding some assets. Before proceeding with this section, please read the [DocPad Overview Page](/start/overview) so you know what each of the directories inside our website structure are for. #### Images Let's add our logo to our layout's header. We'll download the [DocPad logo](https://raw.githubusercontent.com/bevry/designs/1437c9993a77b24c3ad1856087908b508f3ceec6/docpad/flyers/docpad-youtube.gif) and place it in our `static` directory at `source/static/images/logo.gif` (binary files should *always* go in the `static` directory). Then, we'll add it to the body of our layout, to show our logo on each page: {% code title="source/layouts/default.html.eco" %} ```markup

<%= @document.title %>

<%- @content %> <%- @getBlock("scripts").toHTML() %> ``` {% endcode %} If you are downloading the file directory into the specified location, you may have to restart DocPad. We're working on this. #### Stylesheets Now let's make all of our `h1` headers red, by adding a stylesheet file in our render directory at `source/render/styles/style.css`that contains: {% code title="source/render/styles/style.css" %} ```css h1 { color: red; } ``` {% endcode %} Then, to include it in our pages, we'll update the *styles Block* in our `default.html.eco` layout to: {% code title="source/layouts/default.html.eco" %} ```markup <%- @getBlock("styles").add(["/styles/style.css"]).toHTML() %> ``` {% endcode %} Upon saving, we'll notice that our browser will automatically reload, and that our CSS file will be injected into the layout making our header red! #### Scripts Now let's add a nifty loading effect using JavaScript and the [jQuery JavaScript Library](http://jquery.com/). As always, there's plenty of other JavaScript Libraries you can use, but in this guide we'll go with jQuery. To do this, we'll first download the [jQuery library](http://code.jquery.com/jquery.js) file and put it in our `static` directory at `source/static/vendor/jquery.js`. The reason we use the `static` directory for vendor files is that it is extremely unlikely we'll ever want to render any vendor files, so having them there is a good choice for consistency and speed. Whereas, we will probably eventually want to render our own scripts and styles with something, so generally we'll just put them in the render directory to make the transition to rendering engines easier. Now that we have included jQuery in our project, we'll add our nifty loading effect by adding a script file at `source/render/scripts/script.js` that contains: {% code title="source/render/scripts/script.js" %} ```javascript (function(){ $("body").hide().fadeIn(1000); })(); ``` {% endcode %} Now that's done, let's add those files to our *scripts Block* in our `default.html.eco` layout: {% code title="source/layouts/default.html.eco" %} ```markup <%- @getBlock("scripts").add(["/vendor/jquery.js","/schripts/script.js"]).toHTML() %> ``` {% endcode %} Upon saving, we'll notice that our content will fade in over a duration of two seconds. Nifty! Now, some of you may wonder why we omitted the [jQuery onDomReady](http://api.jquery.com/ready/) handler in our script file. While off-topic for DocPad, the reasoning for this is that only code that requires the entire DOM to be loaded needs it. For instance, if your script requires a DOM element that is positioned after our `script` tag, then it would be useful. In this instance, as we inject our scripts into our `body` element, we already have access to the `body` element, and therefore can start our `fadeIn` animation immediately. This avoids the page loading, then, the DOM loading after a delay, followed by our fade-in with an undesirable "popping" effect. ### Getting the benefits of Pre-Processors *Pre-Processors* are amazing things. They allow us to write `render` files in one language (the source language), and export them to a different language (the target language). This is extremely beneficial, as it allows you to use the syntax that you enjoy, instead of the syntax that you are sometimes forced to work with. Most importantly, however, pre-processors often offer more robust and clean functionality than the target language supports out of the box, allowing you to make use of modern development tools while still working with old languages. #### Using Markdown, an HTML Pre-Processor HTML's verbose syntax is terrible for writing content that is more text than markup (e.g., articles, comments, etc.). Fortunately, [Markdown](http://daringfireball.net/projects/markdown/) (one of the many HTML Pre-Processors available to us as [Plugins](https://docpad.org/docs/plugins)) comes to the rescue! Install the [Marked Markdown Plugin](https://github.com/docpad/docpad-plugin-marked) by running `docpad install marked`. Then, rename the *About* page we created earlier from (`source/render/about.html`) to (`source/render/about.html.md`), to indicate that we want to render from Markdown to HTML, and open it. Writing in Markdown, update its content (leave the existing meta data section as it is) to become: ``` I like long walks on the beach. **Plus I rock at DocPad!** ``` Which gives us the same result, but with all the benefits of Markdown! This simple procedure can be followed irrespective of your desired HTML pre-processor. Sweet, you're now ready to party, Markdown-style! ;) #### Using Stylus, a CSS Pre-Processor Open the Stylesheet document we created earlier (`source/render/styles/style.css`). CSS really hasn't come that far over the years and, thus, it has absolutely no abstractions available to us, making it incredibly verbose and painful to write. Fortunately, [Stylus](http://learnboost.github.com/stylus/) (one of the many [CSS Pre-Processors](/community/plugins#css-pre-processors) available to us) is our saviour! Install the [Stylus Plugin](https://github.com/docpad/docpad-plugin-stylus) by running `docpad install stylus`. Then, rename `source/render/styles/style.css` to `source/render/styles/style.css.styl`, to indicate we want to render from Stylus to CSS, and open it. The reason why we created the style file in `render` and not in `static` is now obvious: if the Stylus stylesheet file were in `source/static/styles/` folder, it would not have been pre-processed before copying to `out`. Using Stylus syntax, update the stylesheet's content to become: ``` h1 color: red ``` Which gives us the same result as before, but with all the benefits of Stylus. This simple procedure can be followed irrespective of your desired CSS pre-processor. Sweet, you're now ready to rock the house with Stylus! #### Using CoffeeScript, a JavaScript Pre-Processor Sometimes people can get quite irritated with JavaScript's verbosity, and very annoyed at its nit-picking, such as when they forget a single comma somewhere and their entire app breaks. Fortunately, [CoffeeScript](http://coffeescript.org/) (one of the many [JavaScript Pre-Processors](/community/plugins#javascript-pre-processors) available to us) restores our sanity! Install the [CoffeeScript Plugin](https://github.com/docpad/docpad-plugin-coffeescript) by running `docpad install coffeescript`. Then rename `source/render/scripts/script.js` to `source/render/scripts/script.js.coffee`, to indicate we want to render from CoffeeScript to JavaScript, and open it. Using CoffeeScript, we can update our file's content to become: {% code title="source/render/scripts/script.js.coffee" %} ```coffeescript $("body").hide().fadeIn(1000) ``` {% endcode %} Which gives us the same result, but with all the benefits of CoffeeScript. This simple procedure can be followed irrespective of your desired JavaScript pre-processor. Sweet! Now you're ready to relax, with a rich cup of CoffeeScript. ### Adding some Template Data and Template Helpers via a Configuration File #### Purpose of a Configuration File The [DocPad Configuration File](/core/config) allows us to configure our DocPad instance, listen to events and perform some nifty abstractions. Consider the case where our document title is empty. With our current solution, the title of the page would be `| My Website`. A page title of `My Website` would look far better when our document doesn't have a title. To handle this, we update our title code in our `default.html.eco` layout template to become: {% code title="source/layouts/default.html.eco" %} ```markup <%= if @document.title then "#{@document.title} | My Website" else "My Website" %> ``` {% endcode %} Which would achieve the immediate goal, but then would mean that we would have to update the website title in two places if we want to use anything other than `My Website`. Considering this a common requirement, it would be nice if we could abstract it out, say, into a configuration file! DocPad should have created an application-wide configuration file for us at `docpad.coffee` (in the project root) when we initialized the project. If not, let's create it, with the following contents: {% code title="docpad.coffee" %} ```coffeescript # Define the Configuration docpadConfig = { # ... } # Export the Configuration module.exports = docpadConfig ``` {% endcode %} Notice that the `docpadConfig` object is written in CoffeeScript's version of JSON. You'll have to restart DocPad so that DocPad can become aware of the configuration file. From then on, DocPad will automatically reload your configuration when changes occur. The first part of this configuration is where we actually define our configuration (where the `# ...` is located), and the second part is a [Node convention](http://nodejs.org/docs/latest/api/modules.html#modules_module_exports) for exporting data from one file to another. Whenever we add some configuration, you'll want to add it to the `docpadConfig` object we just defined. For more information on configuration files and what configuration is available to your, refer to our [Configuration Page](/core/config). #### Using TemplateData for Abstractions Everything that is available to our templates is called [Template Data](/core/template-data). For instance, `@document` is part of our template data. To be able to abstract out something that our templates will use, we will need to extend our template data. We can do this by modifying our template data configuration property in `docpad.coffee` like so: {% code title="docpad.coffee" %} ```coffeescript docpadConfig = { templateData: site: title: "My Website" } ``` {% endcode %} With that, our website title is now abstracted and we can update our title element in the `default.html.eco` template: {% code title="source/layouts/default.html.eco" %} ```markup <%= if @document.title then "#{@document.title} | #{@site.title}" else @site.title %> ``` {% endcode %} However, if we really wanted to (and we probably do) we can abstract out that logic into a function inside our template data. #### Abstracting Logic into Template Helpers When using `.coffee` or `.js` files to define our Configuration File, we are allowed to define functions. Doing so allows us to use functions within our template data, which we call *Template Helpers*. When calling a template helper, the scope of the template helper is exactly the same as the scope of whatever is calling it. This makes abstracting out logic really easy. Let's see what our object in `docpad.coffee` would look like: {% code title="docpad.coffee" %} ```coffeescript docpadConfig = { templateData: site: title: "My Website" getPreparedTitle: -> if @document.title then "#{@document.title} | #{@site.title}" else @site.title } ``` {% endcode %} And the title of our layout template, `default.html.eco`, would become: {% code title="source/layouts/default.html.eco" %} ```markup <%= @getPreparedTitle() %> ``` {% endcode %} Now that is awesome! While this was a simple example, we can use it to do some really cool stuff. For instance, [here](https://gist.github.com/4166882) is an example of it being used to localize dates into French. If you're writing a plugin, you can use the [`extendTemplateData`](/core/events#extendtemplatedata) event to extend the template data. ### Adding a Menu Listing for our Pages Remember our *About* page? Wouldn't it be nice if, when we list more pages, our menu updates automatically? It sure would, so let's do that! #### Updating our Layout Open your default layout, and add the following before the `h1`: {% code title="source/layouts/default.html.eco" %} ```markup ``` {% endcode %} Save it, and BANG! Now we've got our navigation menu on each page! Wicked. So what does that do? Well first it uses the `getCollection` [template helper](/core/template-data#standard-template-helpers) to fetch the `html` collection, which is a pre-defined collection by DocPad that contains all the HTML documents in our website. Then, with that collection, we find everything that has a `isPage` attribute set to `true`. (We defined it earlier, when first applying our layout to our pages.) Then, we convert the result from a [Backbone Collection](http://backbonejs.org/#Collection) / [QueryEngine](https://github.com/bevry/query-engine) into a standard JavaScript Array using [`toJSON`](http://backbonejs.org/#Collection-toJSON). That's a bit of a mouthful, but give it a while and you'll be a pro in no time. There is one major inefficiency with the above approach. Can you guess what it is? Performing the query every single time we render a layout is a bit silly, as the results won't change each time. What we ought to do is query once and provide access to the results of our collection. Let's do it! #### Creating Custom Collections via the Configuration File Let's go back to our [DocPad Configuration File](https://docpad.org/docs/config) (`docpad.coffee`) and open it up. This time we want to add the following: {% code title="docpad.coffee" %} ```coffeescript docpadConfig = { collections: pages: -> @getCollection("html").findAllLive({isPage:true}) } ``` {% endcode %} In our default layout, `default.html.eco`, we'll update the `getCollection` line to become: {% code title="source/layouts/default.html.eco" %} ```markup <% for page in @getCollection("pages").toJSON(): %> ``` {% endcode %} Much better, and way more efficient. Did you spot the difference with the call we used? When performing our query, we used the `findAllLive` instead of the `findAll` method. That's because `findAllLive` uses [QueryEngine's Live Collections](https://github.com/bevry/query-engine), which allows us to define our criteria once, and then continue to keep our collection up-to-date. It works by creating a live child collection of the parent collection. (In this case, the `html` collection is the parent collection and our `pages` collection is the child collection.) The child collection then subscribes to the parent collection's `add`, `remove`, and `change` events, and tests the model that the event was for against our child collection's criteria. If it passes the collection, it adds it; if not, then it removes it. This performs much better than querying everything every single time. So then, what about sorting? That's easy enough! We can sort by changing `@getCollection('html').findAllLive({isPage:true})` to add a second argument, which is the sorting argument; `@getCollection('html').findAllLive({isPage:true},[{filename:1}])` that, in this case, will sort by the filename in ascending order. To sort in descending order, we would change the `1` to become `-1`. Now we can sort by any attribute available on our models, which means that we could even add an `order` attribute to our document meta data and then sort by that if we wanted to. There is also a third parameter for paging. To learn about this, as well as what type of queries are available to you, check out [QueryEngine Guide](https://github.com/bevry/query-engine). #### Setting Default Meta Data Attributes for our Pages Considering we'd probably like all our pages to use the default layout, we may be lazy enough to want to set this by default for all our pages, so we don't always have to add `layout: default` to the [meta data](/core/meta-data) of each page. Just like everything, it's pretty darn easy, if you know how. And here's how: {% code title="docpad.coffee" %} ```coffeescript docpadConfig = { collections: pages: -> @getCollection("html").findAllLive({isPage:true}).on "add", (model) -> model.setMetaDefaults({layout:"default"}) } ``` {% endcode %} So, what does this do? It's exactly the same as before, but we use the `add` event automatically fired by [Backbone](http://backbonejs.org/#Collection-add) whenever a model (a page, file, document, whatever) is added to our collection. Then, inside our event, we say we want to set our default meta data attributes for the model; in this case, setting the layout to `"default"`. This is invaluable when doing more complex things in DocPad. For instance, we use it for this documentation, to allow us to base the navigation structure of our documentation files on their physical location in our file system. Thus, if we have a file `docs/docpad/01-start/04-begin.html.md`, we can detect that the project is `docpad`, and assign `project: "docpad"` to the meta data accordingly. As the section is "start" and it is order first, we set `category: "start"` and `categoryOrder: 1`. We also see that our file is `begin` and ordered 4th. This is just one nifty example. There's plenty more you'll discover on your own epic journey! :) ### Adding the Blog Posts As you now have all the tools and knowledge required to be able to create the blog post section, we've left that part as an exercise for you! We've done this to help you retain and make best use of all the awesomeness you've just learned. * If you need a few pointers to help you get started, here you go :) * Create a new layout called `post` that will use the default layout. Use it to perform custom styling for your blog post (e.g., `
<%- @content %>
`). * When creating your blog posts, we recommend giving them a `date` meta data attribute in the format of `date: 2012-12-25`, so you can sort your blog posts in descending date order. * Create a new directory called `posts` that contains all of your blog posts, and use the query `relativeOutDirPath: 'posts'` for your custom collection in order to retrieve all documents in the `posts` output directory (`/my-new-website/out/posts`). You can refer to the [Meta Data Page](/core/meta-data) for more information about the attributes already available to you. * Create a new page called `posts.html.eco` that lists all your blog posts. This will be, more or less, the same as our navigation menu. If you would like to display descriptions of the blog posts, just add that as a meta data attribute for the blog posts, and then output that meta data attribute. If you want to show the rendered content of the data, you can use `post.contentRenderedWithoutLayouts`. You can refer to the [Meta Data Page](/core/meta-data) for more information about the attributes already available to you. * If you're stuck and need some help, refer to available Support Channels via our [Support Page](/start/support). Congratulations! You now possess all the foundations required to be able to write amazing and powerful web applications like those already in our [Showcase](/community/showcase). To recap, you now know how to: * write `render` files in any language, markup, pre-processor, templating engine, whatever you wish, by installing the necessary plugin for it and changing the extensions of the document * perform powerful abstractions using layouts, meta data, template data and configuration files * create incredibly efficient custom collections, filtered and sorted by your own criteria * do your own custom listings of content But it doesn't stop there; these were just the foundations! If you can imagine it, then you will be able to accomplish it with DocPad. Really, there are no limits - that's why DocPad sets you free! So, farewell and enjoy your epic journey. The power is yours! # Deploy DocPad websites can be deployed anywhere. Here are a few of the most common deployments. ### Deploying DocPad #### Preparing DocPad for Deployment 1. Ensure your project's `package.json` file contains the following: 
 "engines" : {
        "node": "6",
        "npm": "3"
    },
    "dependencies": {
        "docpad": "6",
        "docpad-plugin-blah": "2"
    },
    "main": "node_modules/.bin/docpad-server",
    "scripts": {
        "start": "docpad-server",
        "test": "docpad generate --debug --silent --env static",
        "info": "docpad info --silent"
    }
Correct dependencies with what you are actually using. ### To Static Servers (Apache, Nginx, etc.) #### For deployment to a Custom Static Server 1. Perform a generation for a static production environment using `docpad generate --env static` 2. Upload the generated directory to your server's `public_html` or `htdocs` directory 1. If you use rsync, [checkout our DocPad rsync deploy script](https://gist.github.com/Hypercubed/5804999) #### For deployment to [GitHub Pages](http://pages.github.com/) 1. Install the [GitHub Pages Plugin](https://github.com/docpad/docpad-plugin-ghpages) ```bash docpad install ghpages ``` 2. Deploy to GitHub Pages using the plugin ```bash docpad deploy-ghpages --env static ``` 3. If you'd like deployment automatically to GitHub Pages every time your repo updates, check out the [Continuous Deployment Guide](https://docpad.org/docs/deploy#using-circle-ci-to-deploy-to-github-pages) #### For deployment to a Cloud Data Storage Provider (AWS S3, Google Storage, etc.) 1. [Checkout the DocPad Sunny Plugin](https://github.com/bobobo1618/docpad-plugin-sunny) ### To a Node.js Hosting Provider #### For deployment to [Heroku](http://www.heroku.com/) 1. Create a `Procfile` file inside your project that contains: 
 web: npm start
2. Set your heroku instance to run in production mode ``` heroku config:add NODE_ENV=production ``` 3. [Follow the rest of the Heroku guide here](http://devcenter.heroku.com/articles/node-js) 4. If you're also wanting to use custom domains for your website, [follow the Heroku Guide here](https://devcenter.heroku.com/articles/custom-domains), or alternatively here is a generic guide: 1. Login to your domain's DNS manager 2. Create an CNAME Record for your domain pointing to your app url (e.g., `balupton.herokuapp.com`) #### For deployment to [OpenShift](https://openshift.redhat.com/) 1. Create your [OpenShift](https://openshift.redhat.com/) account and [install their client tools](https://developers.openshift.com/en/managing-client-tools.html) 2. Create a new OpenShift application for your project: ```bash rhc app create PROJECTNAME https://raw.githubusercontent.com/kyrylkov/openshift-iojs/master/metadata/manifest.yml ``` 3. Set environment variables using: ```bash rhc set-env -a PROJECTNAME NODE_ENV='production' ``` 4. If you'd like a custom domain, run: ```bash rhc alias-add PROJECTWEBSITE.COM -a PROJECTNAME ``` Then create CNAME record with your DNS host pointing `PROJECTWEBSITE.COM` to `PROJECTNAME-YOUR_OPENSHIFT_NAMESPACE.rhcloud.com` If you don't know what your OpenShift namespace is, run: ```bash rhc app show -a PROJECTNAME ``` And it will be listed within the SSH URL. 5. Deploy your project's code to openshift: ```bash rhc app deploy "https://github.com/USER/REPO.git#master" -a PROJECTNAME ``` 6. You should be all good now! Check the logs of your app with: ```bash rhc tail -a PROJECTNAME ``` #### For deployment to [Windows Azure](http://azure.microsoft.com/en-us/services/app-service/web/) 1. Create a deployment script that triggers the static content generation. To create the script run the following command using the [Windows Azure Cross-Platform Command-Line Interface](http://azure.microsoft.com/en-us/documentation/articles/xplat-cli/): ```bash azure site deploymentscript --basic -t bash ``` 2. Modify the `deploy.sh` file by changing the `# Deployment` section to the following lines. You can see a complete example of the deploy.sh file [here](https://gist.github.com/ntotten/4715760#file-deploy-sh). 
 echo Handling deployment.

    # 1. Install npm packages
    if [ -e "$DEPLOYMENT_SOURCE/package.json" ]; then
      cd "$DEPLOYMENT_SOURCE"
      npm install --production --silent
      exitWithMessageOnError "npm failed"
      cd - > /dev/null
    fi

    # 2. Build DocPad Site
    echo Building the DocPad site
    cd "$DEPLOYMENT_SOURCE"
    npm test
    exitWithMessageOnError "DocPad generation failed"

    # 3. KuduSync
    echo Kudu Sync from "$DEPLOYMENT_SOURCE/out" to "$DEPLOYMENT_TARGET"
    $KUDU_SYNC_COMMAND -q -f "$DEPLOYMENT_SOURCE/out" -t "$DEPLOYMENT_TARGET" -n "$NEXT_MANIFEST_PATH" -p "$PREVIOUS_MANIFEST_PATH" -i ".git;.deployment;deploy.sh" 2> /dev/null
    exitWithMessageOnError "Kudu Sync failed"
3. Last, create a `web.config` file in the `static` directory of your site with the URL rewrite rules shown below. These rules remove the HTML extensions from your URLs. You can see the main portions of this `web.config` file below. You can download the complete file [here](https://gist.github.com/ntotten/4715760#file-web-config). 
 <rule name="RemoveHTMLExtensions" stopProcessing="true">
        <match url="^(.*)\.html$" />
        <action type="Redirect" url="{R:1}" appendQueryString="true" />
    </rule>
    <rule name="RewriteHTMLExtensions" stopProcessing="true">
        <match url="(.*)" />
        <conditions>
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true"/>
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true"/>
        </conditions>
        <action type="Rewrite" url="{R:1}.html" />
    </rule>
4. [Follow the rest of the Azure guide here](http://blog.ntotten.com/2013/01/11/static-site-generation-with-docpad-on-windows-azure-web-sites/) #### For deployment to [Modulus](http://modulus.io/) 1. [Follow getting started guide](http://help.modulus.io/customer/portal/articles/1640060-getting-started-guide) #### For deployment to [Docker](https://www.docker.io/) 1. [There is a docker file that should help with deployments.](https://github.com/docpad/dockerfile) ### Continuous Deployment #### To GitHub Pages 1. Inside your project directory, do the following: 1. Add the [GitHub Pages Plugin](https://github.com/docpad/docpad-plugin-ghpages) as a Development Dependency ```bash npm install --save-dev docpad-plugin-ghpages ``` 2. Add a deploy script to your `package.json` `"scripts"` section: 
 {
           "scripts": {
               "deploy": "docpad deploy-ghpages --silent --env static"
           }
       }
3. Remove the `regenerateEvery` property from your DocPad Configuration File if you have set it, as it will no longer be needed. **Using Travis CI** 1. Inside your GitHub account, do the following: 1. [Create a Personal Access Token](https://github.com/settings/tokens/new) called `Travis CI Deployer` that has `repo` and `public_repo` checked (uncheck everything else), make note of the token we'll use it later (this same token can be used for all the repos you have access to). 2. Enable Travis CI for the repository, then inside the repository directory, do the following: 1. Add [this `.travis.yml` file](https://gist.githubusercontent.com/balupton/a10abaf708c835eed154/raw/travisci-main.yml) to your project (make any necessary changes to the Custom Configuration section). 2. Run the following commands (with the appropriate substitutions): ```bash travis encrypt "DEPLOY_USER=$YOUR_GITHUB_USERNAME" --add env.global travis encrypt "DEPLOY_TOKEN=$THE_PERSONAL_ACCESS_TOKEN" --add env.global ``` 3. Commit and push the changes. 3. If you want to regenerate your website when an external GitHub Repository changes (for instance updating the DocPad Website when the DocPad Documentation repository changes), you will need to Enable Travis CI for that repository, then inside that repository directory, do the following: 1. Add [this `.travis.yml` file](https://gist.githubusercontent.com/balupton/a10abaf708c835eed154/raw/travisci-other.yml) to your project (make any necessary changes to the Custom Configuration section). 2. Run the following commands (with the appropriate substitutions): ```bash travis encrypt "GITHUB_TRAVIS_TOKEN=$THE_PERSONAL_ACCESS_TOKEN" --add env.global ``` 3. Commit and push the changes. 4. All done, your next push to master will be automatically deployed. **Using Circle CI** 1. Inside your project directory, do the following: 1. Add [this `circle.yml` file](https://gist.githubusercontent.com/balupton/a10abaf708c835eed154/raw/circleci-main.yml) to your project (make any necessary changes to the Custom Configuration section). 2. Commit and push the changes. 2. Create a SSH Key that will be used by Circle CI to deploy to GitHub Pages, do this by: 1. Create the SSH Key, make note of where it goes, don't bother with a password, use the email that was inside your `circle.yml` file: ```bash ssh-keygen -t rsa -b 4096 -C "circle@bevry.me" ``` 2. Make note of it's location. Two files will be generated. One with `.pub` at the end, which is the public key, and one without `.pub` which is the private key. 3. Inside your Circle CI account, do the following: 1. Add any environment variables you may need via `Project Settings -> Tweaks -> Environment Variables` 2. Add the private key to CircleCI via `Project Settings -> Permissions -> SSH Permissions`. Set the hostname to `github.com`. Use the contents of the private key file for the private key text area. 4. Inside your GitHub Project Settings, do the following: 1. Add the public key to your GitHub Project by going to `Settings -> Deploy Keys -> Add deploy key`. Specify the title as `CircleCI Deployment` or whatever you like and set the key text area to the contents of the public key. Allow write access. 5. If you want to regenerate your website when an external GitHub Repository changes (for instance updating the DocPad Website when the DocPad Documentation repository changes), you will need to: 1. Create yourself a Circle CI token via the [Circle CI Account API Page](https://circleci.com/account/api) 2. Go to the settings of the GitHub Repository that should cause the regeneration, and access `Webhooks & Services -> Add webhook` 1. Specify the `Payload URL` to be: ``` https://circleci.com/api/v1/project/YOUR_GITHUB_ORG/YOUR_GITHUB_REPO/tree/master?circle-token=THE_CIRCLECI_TOKEN ``` 2. Specify `Content type` to be `application/json`, select `Just the push event`, and check `Active` 3. You can hit that Payload URL whenever you want to retest and rebuild your project. 6. All done, your next push to master will be automatically deployed. 1. You can now delete the local SSH key files that were made, as they serve no further purpose. #### To GitLab Pages Project repository must be at [GitLab](https://gitlab.com/). If it is already somewhere else, GitLab allows to setup automatic mirroring. Just add single file `.gitlab-ci.yml` to project root: {% code title=".gitlab-ci.yml" %} ```yaml image: node cache: paths: - node_modules/ pages: before_script: - npm install --production script: - npm test - mv out public artifacts: paths: - public only: - master ``` {% endcode %} Commit, push, wait a minute and enjoy! :-)[
](https://docpad.org/docs/begin) # FAQ ### Does it work on Windows? Sure does. [Install it now.](/start/install) ### 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 `bold`. 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. [We will be addressing this in a future release of DocPad.](https://github.com/bevry/docpad/issues/684) ### 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: * [Eco](https://github.com/sstephenson/eco): `<%= Math.random() %>` * [Jade](http://jade-lang.com/): `= Math.random()` * [Haml](http://haml.info/): `= 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`? DocPad's querying capabilities are provided by a project called [Query-Engine](http://github.com/bevry/query-engine) 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. 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 `findAllLive` when defining long-running custom collections. Typical use cases are via the `collections` property of your [docpad configuration file](/core/config), or via the [`extendCollections` event](/core/events#extendcollections) within your plugin. 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. However, ideally wherever possible you should try to use DocPad's built-in [template helpers](/core/template-data#standard-template-helpers) or [APIs](/core/api) for querying as these methods are highly optimised for DocPad, whereas the low-level Query-Engine methods are not. ### How can I learn more about the NoSQL queries available and the internals of Query-Engine? [Take a look at the Guide to Using Query-Engine](https://learn.bevry.me/queryengine/guide) ### How do I hide a document from being rendered (e.g., a draft post)? Check out the `ignored` [meta data property](/core/meta-data). ### How do I re-render a document on each request (e.g., dynamic documents)? Check out the `dynamic` [meta data property](/core/meta-data). ### 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? Templating engines are renderers for languages which support business logic. For instance, the template engine [Eco](https://github.com/sstephenson/eco) 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`. [Check out the full listing of template data & helpers here.](/core/template-data) 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? All environment variables are automatically available in Node applications through [`process.env`](http://nodejs.org/api/process.html#process_process_env). DocPad also loads variables from a special [environment file](/core/config#environment-configuration-file). 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? Check out the `enabledPlugins` [configuration property](/core/config). ### How do I only enable the plugins that I actually use? Check out the `enableUnlistedPlugins` [configuration property](/core/config). ### How do I customise the configuration sent to a plugin? Check out the `plugins` [configuration property](/core/config). ### Where can I host my DocPad website? [Check out our deployment section here.](/start/deploy) ### How can I get Jade to render other DocPad supported markups? [Check out the usage section on the Jade Plugin.](https://github.com/docpad/docpad-plugin-jade#usage) ### How can I get my templating engine to render other DocPad supported markups? [Check out the text plugin.](https://github.com/docpad/docpad-plugin-text/) ### How can I re-use particular templates again and again throughout my site? [Check out the partials plugin.](https://github.com/docpad/docpad-plugin-partials/) ### How do I make DocPad detect file changes faster? Check this [GitHub issue](https://github.com/bevry/docpad/issues/749), see if it helps. :) ### Cannot get past accepting the Terms of Service Check this [GitHub issue](https://github.com/bevry/docpad/issues/854) for a conversation on this bug. 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? [Visit our support page.](/start/support) # Troubleshoot ### 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 [this workaround](https://github.com/bevry/docpad/issues/488). #### I got "npm ERR! Failed to parse json" Check your project's `package.json` file with [JSONLint](http://jsonlint.com/), 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 [recommended installation instructions](http://bevry.me/node/install). #### When I run `npm install` on windows, I get `gyp ERR! configure error` * For Windows XP/Vista/7 installations: * [Python](http://www.python.org/download/) [v2.7.8](http://www.python.org/download/releases/2.7.8#download) Recommended * [Microsoft Visual Studio C++ 2010](http://go.microsoft.com/?linkid=9709949) * For 64-bit builds of Node.js and native modules, you'll also need: * [Windows 7 64-bit SDK](http://www.microsoft.com/en-us/download/details.aspx?id=8279) * 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: * [compiler update for the Windows SDK 7.1](http://www.microsoft.com/en-us/download/details.aspx?id=4422) * For Windows 7/8: * [Microsoft Visual Studio C++ 2012 for Windows Desktop](http://go.microsoft.com/?linkid=9816758) #### When I run `docpad run` on Windows, it asks me what program I would like to open the file in 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. [More information here.](https://github.com/bevry/docpad/issues/561#issuecomment-21494426) #### 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. To do this, add the following to your [DocPad configuration file](/core/config): ```coffeescript watchOptions: preferredMethods: ['watchFile','watch'] ``` Mac OS X users are most likely to encounter this issue. #### Watching is very slow to notice changes Add the following to your [DocPad configuration file](/core/config): ```coffeescript regenerateDelay: 0 watchOptions: catchupDelay: 0 ``` This will introduce problems however if you have previously customised `watchOptions`, or if your editor uses swapfiles. [More info here.](https://github.com/bevry/docpad/issues/749) #### Error: "We couldn't find an existing DocPad project inside your current directory..." 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 [skeleton](/community/showcase#skeletons) 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 [Getting Started](/start/begin) guide. Hope that helps :) [If you need more help then check out our Support Channels](/start/support). #### Error: "Could not locate git binary" This happens when the [git](http://git-scm.com/) installation is not exposed to your [`PATH` variable](http://en.wikipedia.org/wiki/PATH_%28variable%29). You can solve this in either of these two ways: * 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 [More information about this here.](https://github.com/bevry/docpad/issues/425) #### 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: * [Move files that you do not reference in content listings to a raw directory with the raw plugin](https://github.com/bevry/docpad/issues/276) * [Set `standalone: true` to the meta data of documents that you regenerate often](/core/meta-data) * Use native/JavaScript implementations of renderers instead of non-native, non-JavaScript ones * (e.g., instead of using SASS, use nodesass, Stylus, or Less) * [Help us implement performance optimisations](https://github.com/bevry/docpad/issues/529) #### I upgraded, and it doesn't work [Check out the Upgrade Guides here](/start/upgrade) #### Whenever I output a variable (like `content`) it is escaped (`<` rendered as `<`)? Template engines by default *escape* all variable output. Escaping is when we turn things like the open bracket `<` into its *html entity* equivalent `<`. 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 If you are using [Dropbox](http://j.mp/dropbox-bal) (an online syncing and backup tool) and your project is inside your Dropbox folder, then click the Dropbox menu icon and select "Pause Syncing". 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. If you're still experiencing issues, then be sure to post about it on the [issue tracker](https://docpad.org/issues). #### The Growl notifications aren't displaying This means you need to [download and install the growlnotify extra](http://growl.cachefly.net/GrowlNotify-1.3.zip) from the [Growl website](http://growl.info/). This package provides a command line application for calling Growl, which can then be used by DocPad. #### 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? [Visit our support page.](/start/support) # Support ### Support Channels [Check out our Support Channels.](https://docpad.bevry.me/support) ### Consulting Partners DocPad also has several partners whom provide consulting and support services for DocPad. ### [Bevry. Tier 3 Support/Advisory.](https://bevry.me/support) Bevry are the creators of DocPad and are available for advisory, training, sponsorship, and prioritized development. ### [Almero. Medium to Corporate Sized Clients.](http://almero.bg/) Almero is a digital marketing agency based in Bulgaria, specializing in providing services that seamlessly incorporate market analysis, user insights, strategic and tactical brand development, graphic design, web design, advertising and video production. Almero has experience building corporate sites with DocPad, and use DocPad almost exclusively for their web projects. ### [DockYard. Small to Corporate Sized Clients.](http://dockyard.com/) We are designers, software engineers, and storytellers, creating beautiful products and building brands. Based out of Boston, MA & Washington, DC, we build web & mobile-web applications using Ruby on Rails, PostgreSQL, and Ember.js. We provide services and support for many tech solutions, including our favorite static website generator: DocPad. ### [Myplanet Digital. Enterprise Clients.](https://www.myplanet.com/) Myplanet is a digital product development company based out of Toronto, Canada. They funded the development of DocPad’s [importer functionality](https://github.com/bevry/docpad/issues/500). They value building the right product, fast. Working with their clients, Myplanet Digital brings startup thinking to enterprise. # Upgrade ### Upgrade Instructions To upgrade your DocPad installation from an older version to the latest, check out the [latest installation instructions](/start/install) as well as the upgrade manuals below. ### Upgrading from 5.x to 6.x (v6 is the latest stable version) * Changes affecting configuration: * Removed the following configuration options: `documentsPath`, `filesPath`, and `layoutsPath`. Use their array-based alternatives instead: `documentsPaths`, `filesPaths`, and `layoutsPaths`. * Changes affecting templates: * Removed `require` from `templateData`. Instead, specify it in your `docpad.cson` or `server.coffee` file instead * Removed `database`, `documents`, `collections`, `blocks` from `templatedata`. Instead, use their helper based alternatives: `getDatabase()`, `getCollection('documents')`, `getCollection('collectionName')`, `getBlock('blockName')` * Changes affecting everyone: * Removed the prototypes `String::startsWith`, `String::finishesWith`, `Array::hasCount`, `Array::has` as no one ever used them * Plugin versions have been bumped to `2.x` for DocPad v6.x compatibility. You should update all your DocPad plugins versions in your `package.json` to `2.0.x` (e.g., `"docpad-plugin-eco": "2.0.x"`) then run `npm install` to install the new versions of the plugins * Changes affecting plugin developers: * Removed `docpadInstance.documents`. Use `docpadInstance.getCollection('documents')` instead. * Plugin tests are now run via `npm test` on your plugin directory, allowing you to use whatever test runner you want * DocPad and the tester helpers have moved from Mocha to [Joe](http://github.com/bevry/joe), you'll probably want to do the same ### Upgrading from 4.x to 5.x 1. Documents, Partials and Layouts (which extend from the File Class) are now [Backbone Models](http://backbonejs.org/#Model) * For end-users this will have minimal effect, as `@document` inside the `templateData` will have all the same attributes. However, any function calls will now only be accessible via the new `@documentModel`. This is because `@documentModel` is the backbone model, and `@document` is the JSONified version of the backbone model (e.g., `@document` is the same as `@documentModel.toJSON()`). * For plugin developers this affects how you will retrieve and set attributes for documents - which now use the [Backbone getters and setters](http://backbonejs.org/#Model-get) instead of directly reading and writing to and from the attributes directly (e.g., `document.relatedDocuments = []` now becomes `document.set(relatedDocuments:[])` instead) 2. [Query-Engine](https://github.com/bevry/query-engine) has been updated from version 0.6 to version 1.1 * For end-users this will have an effect wherever `@database` is used, as that is now represented by the new Query-Engine v1.1 collection, which has several changes. The most significant re `@database.find` is now `@database.findAll`, and that they now only have a synchronous interfacee. E.g. the `@database.findAll` selector `(err, results) ->` should now be `results = @database.findAll(selector)` * For plugin developers, this affects any `docpad.documents`, `docpad.partials`, and `docpad.layouts` calls with the same advice as those for end-users. 3. Plugins are now handled via [npm dependencies](https://docs.npmjs.com/getting-started/installing-npm-packages-locally) instead of being directly handled by DocPad and end-users. This is the most significant change and affects everybody. * For end-users, you will need to add the plugins you use to your website's `package.json` file. You can refer the [`package.json` file of the `canvas.docpad` skeleton here](https://github.com/bevry/canvas.docpad/blob/docpad-5.x/package.json#L30-43) for how to do this. Once added to your website's `package.json` file, run a `npm install` to install them. * For plugin developers, there have been several important changes: 1. All plugins must now have `docpad-plugin` inside the `keywords` property of their `package.json` file. It is also highly recommended to ensure your plugin's name follows the `docpad-plugin-#{pluginName}` convention as this may become mandatory at a later date. 2. You can now feel free to publish your plugin via npm (e.g., `npm publish`) and add your plugin to the [Plugins page](/community/plugins) so others can install it themselves (e.g., `npm install docpad-plugin-#{pluginName}`). ### Upgrading from 3.x to 4.x 1. Skeletons are no longer cached, which means that you can no longer create a new website using a skeleton while offline. While this can be a pain, it was an essential change in order to improve stability and reduce complexity of the code base. 2. A document's `title` will no longer default to the document's `filename` if not set. Instead a new property called `name`exists, which can be set by your document meta data. This is so the `title` property can be used for Page Titles (e.g., ``) whereas the `name` property can be used for navigation listings etc. 3. The DocPad core has been cleaned up a lot, and as such so has the way plugin events are triggered. We now utilise [balUtil's](https://github.com/balupton/bal-util.npm) [emitSync](https://github.com/balupton/bal-util.npm/blob/master/lib/events.coffee#L257) and [emitAsync](https://github.com/balupton/bal-util.npm/blob/master/lib/events.coffee#L241) instead of the old `triggerPluginEvent`. This means that for now, plugin priorities are discarded - however they may be added back in the future (so leave them in there if you have them). 4. Plugin rendering has had a significant change, which is you should no longer use `file.content` to read and update the current document's content. Instead a new argument called `content` wil be passed, and it should be written to as well. This is a breaking change, and all renderers must be updated to facilitate this change. To learn the new way, then check out the [Extending DocPad](/extend/extend) wiki page. 5. When an error occurs, the error will now be sent back to DocPad using the [AirBrake](http://airbrake.io/) service. If you would like this disabled then you can turn it off by setting `reportErrors` to `false` in your DocPad configuration. 6. A lot of unstable or less-popular plugins have been moved out to the new [docpad-extras](https://github.com/bevry/docpad-extras) repository. The plugins moved are: `admin`, `authenticate`, `autoupdate`, `buildr`, `html2jade`, `move`, `php`, `rest`, `roy`, and `ruby`. If you would like to continue using them, you will have to download them manually from the `docpad-extras` repository and insert them into your website's `plugins` directory. ### Upgrading from 2.x to 3.x <a href="#upgrading-from-2-x-to-3-x" id="upgrading-from-2-x-to-3-x"></a> 1. A lot of property names of the `File` class have changed. The `File` class is used for all documents and layouts, which would likely affect you when rendering properties from documents inside your templates e.g. `@document.title`. This change was made to better correlate the names with their values (before the correlation was quite ambiguous). [You can find the current set of properties and their descriptions here.](https://github.com/bevry/docpad/blob/master/lib/file.coffee#L12) 2. For plugin developers, the way you extend from the `BasePlugin`, and the way you `module.exports` your plugin has changed. [To learn about the new convention, refer to the new *Extending* guide by clicking here.](/extend/extend) 3. For those using DocPad as a module, DocPad now supports a `next` callback on its constructor, allowing you to do `new DocPad(config,next)`. Anything that depends on a DocPad action being completed should go inside the `next`callback. While this is optional, it has proven helpful in eliminating timing problems. ### Upgrading from 1.x to 2.x <a href="#upgrading-from-1-x-to-2-x" id="upgrading-from-1-x-to-2-x"></a> 1. CoffeeScript v1.1.2 does not work with Node 0.5 or 0.6, you have to use v1.1.3 or higher. To do this, re-install CoffeeScript with `npm install -g coffee-script` 2. For plugin developers: 1. Plugins have been revised to become more future proof and configurable. Plugins must be in their own directory, with the following format: `plugins/${pluginName}/${pluginName}.plugin.coffee` 2. Plugin dependencies should no longer be in the DocPad's or your project's `package.json` file, but instead in their plugin directory's `package.json` (e.g., `plugins/${pluginName}/package.json`); this file is optional, but recommended. 3. If a plugin's `package.json` exists, as well as its `main` property, DocPad will use that as the plugin file's location instead of the location in step 2.1. 4. Plugin configuration should be moved to their `package.json` file, to the key `docpad.plugin` which should be an object. This is then customisable by DocPad's `package.json` as well as the website's via `docpad.plugin.#{pluginName}`. The configuration of a plugin is available via the `@config` property. 5. To access DocPad within a plugin, you should now use `@docpad` rather than having it passed through as an argument, this applies for logger too (now use `@logger`). 6. A lot of DocPad configuration has been moved to `@docpad.config` 3. DocPad v2 also brings a bunch of new cool features, check out the changelog on the [homepage](https://github.com/balupton/docpad) for more info, and the [FAQ](/start/faq) for information on how to use some of these new features :-) 4. The Bootstrap Skeleton is now the [Kitchensink Skeleton](https://github.com/balupton/kitchensink.docpad) ### Upgrading from 0.x to 1.x <a href="#upgrading-from-0-x-to-1-x" id="upgrading-from-0-x-to-1-x"></a> 1. Install DocPad with the new global dependencies `npm install -g coffee-script docpad` 2. Any of your `documents` or `layouts` which use the eco templating engine should have the extension `.eco` appended (e.g., `layouts/default.html` to `layouts/default.html.eco`) 3. Any of your `documents` or `layouts` which utilise a markup language should have the extension `.html` prepended (e.g., `documents/something-in-markdown.md` to `documents/something-in-markdown.html.md`) 4. These changes allow for some new incredibly powerful possibilities, such as allowing other templating engines other than eco, and allowing for multiple and more explicit markups to be applied to the files. # Performance A list of performance optimisations that you should be aware of. ### Using the [raw](https://github.com/docpad/docpad-plugin-raw) plugin <a href="#using-the-raw-plugin" id="using-the-raw-plugin"></a> This plugin allows you to quickly copy files that are found in the `/src/raw` directory to the `/out` directory without going through DocPad's rendering, thus making it a much quicker process. Especially useful if placing them in the `/src/static` (or `/src/files`) folder is still slow. Check the [plugins section of the DocPad docs](/community/plugins) for instructions on how to install plugins. # API This page will go over using DocPad as a module, and the API available to you. ### Technical API <a href="#technical-api" id="technical-api"></a> [DocPad has auto-generated Technical API from its source code, check it out!](http://master.docpad.docpad.surge.sh/docs/) ### Install DocPad <a href="#install-docpad" id="install-docpad"></a> Besides having [Node.js installed](https://learn.bevry.me/node/install), you'll want to install DocPad locally to your project, you can do this by running `npm install --save docpad` in your command line. This will install DocPad into `./node_modules/docpad` and make it accessible via [Node.js's require function](http://nodejs.org/docs/latest/api/all.html#all_require) (e.g., `require('docpad')`) If you are wanting to utilise DocPad for rendering, you'll also want to install some rendering [Plugins](/community/plugins). ### Create your DocPad Instance <a href="#create-your-docpad-instance" id="create-your-docpad-instance"></a> Firstly, you need to create your DocPad instance, you can do this like so: ```javascript var docpadInstanceConfiguration = {}; require('docpad').createInstance(docpadInstanceConfiguration, function(err,docpadInstance){ if (err) return console.log(err.stack); // ... }); ``` ### Rendering individual files <a href="#rendering-individual-files" id="rendering-individual-files"></a> You can use DocPad as a module to render individual files very easily. This allows you to utilise DocPad for all the rendering inside your application, instead of having to *write **and maintain*** specific wrappers for each rendering engine yourself. #### Render some text with DocPad <a href="#render-some-text-with-docpad" id="render-some-text-with-docpad"></a> ```javascript var renderOpts = { text: 'here is some **markdown**', filename:'markdown', renderSingleExtensions:true }; docpadInstance.action('render', renderOpts, function(err,result){ console.log(result); }); ``` #### Render a file path with DocPad <a href="#render-a-file-path-with-docpad" id="render-a-file-path-with-docpad"></a> ```javascript var renderOpts = { path: '/some/file.html.md', renderSingleExtensions:true }; docpadInstance.action('render', renderOpts, function(err,result){ console.log(result); }); ``` ### DocPad CLI Actions <a href="#docpad-cli-actions" id="docpad-cli-actions"></a> Here is how you would normalise common tasks you would typically achieve with the DocPad command line interface. #### Performing a generation <a href="#performing-a-generation" id="performing-a-generation"></a> ```javascript // `generateOpts` is optional var generateOpts = { collection: docpad.getCollection("myChangedPages"), // only regenerate a subset reset:true // default }; // Which means it doesn't have to be included in the function call below docpadInstance.action('generate', generateOpts, function(err,result){ if (err) return console.log(err.stack); console.log('OK'); }); ``` #### Start the DocPad server <a href="#start-the-docpad-server" id="start-the-docpad-server"></a> ```javascript docpadInstance.action('server', function(err,result){ if (err) return console.log(err.stack); console.log('OK'); }); ``` #### Generate and Start the DocPad Server <a href="#generate-and-start-the-docpad-server" id="generate-and-start-the-docpad-server"></a> You can combine actions by separating them with a space, like so: ```javascript docpadInstance.action('generate server', function(err,result){ if (err) return console.log(err.stack); console.log('OK'); }); ``` #### Perform an initial generation, then watch files and regenerate when a change occurs <a href="#perform-an-initial-generation-then-watch-files-and-regenerate-when-a-change-occurs" id="perform-an-initial-generation-then-watch-files-and-regenerate-when-a-change-occurs"></a> ```javascript docpadInstance.action('generate watch', function(err,result){ if (err) return console.log(err.stack); console.log('OK'); }); ``` ### Using the Database <a href="#using-the-database" id="using-the-database"></a> DocPad using [Backbone.js](http://backbonejs.org/) for its Models, and [QueryEngine](https://github.com/bevry/query-engine) for its Collections. Providing a powerful database that you can query in a noSQL type fashion. #### Get the database <a href="#get-the-database" id="get-the-database"></a> ```javascript database = docpadInstance.getDatabase() ``` #### Create a Document and File <a href="#create-a-document-and-file" id="create-a-document-and-file"></a> ```javascript document = docpadInstance.createDocument(data, options) file = docpadInstance.createFile(data, options) ``` #### Create a Document and File, then add it to the Database <a href="#create-a-document-and-file-then-add-it-to-the-database" id="create-a-document-and-file-then-add-it-to-the-database"></a> ```javascript database = docpadInstance.getDatabase() document = docpadInstance.createDocument(data, options) file = docpadInstance.createFile(data, options) database.add(document) database.add(file) ``` #### Parse a Document and File Directory <a href="#parse-a-document-and-file-directory" id="parse-a-document-and-file-directory"></a> ```javascript // options = {path} // next(err, files) docpadInstance.parseDocumentDirectory(options, next) docpadInstance.parseFileDirectory(options, next) ``` #### Querying <a href="#querying" id="querying"></a> ```javascript // Get files, returns a cached live collection resultCollection = docpadInstance.getFiles(query, sorting, paging) // Get a file resultModel = docpadInstance.getFile(query, sorting, paging) // Get files at path (forwards onto getFiles) resultCollection = docpadInstance.getFilesAtPath(path, sorting, paging) // Get a file at a relative or absolute path or URL resultModel = docpadInstance.getFileAtPath(path, sorting, paging) // Get a file by its id resultModel = docpadInstance.getFileById(id, {collection:null}) // Get a file by a route, useful when doing server requests docpadInstance.getFileByRoute(url, function(err, resultModel){ if ( err ) console.log(err.stack) }) ``` [For more information about Querying, check out this FAQ Entry.](https://docpad.org/docs/faq#what-is-findalllive) ### Using with Express <a href="#using-with-express" id="using-with-express"></a> If you already have an Express.js application, you can do the following to just stick DocPad straight ontop of it: ```javascript // Create Server and Express Application var express = require('express'); var http = require('http'); var app = express(); var server = http.createServer(app).listen(8080); // Add our Application Middlewares app.use(app.router); // Add DocPad to our Application var docpadInstanceConfiguration = { // Give it our express application and HTTP server serverExpress: app, serverHttp: server, // Tell it not to load the standard middlewares (as we handled that above) middlewareStandard: false }; var docpadInstance = require('docpad').createInstance(docpadInstanceConfiguration, function(err){ if (err) return console.log(err.stack); // Tell DocPad to perform a generation, extend our server with its routes, and watch for changes docpadInstance.action('generate server watch', function(err){ if (err) return console.log(err.stack); }); }); // Continue with your application // ... ``` Here is some code for manually rendering a document (inside `src/render`) with a custom route: ```coffeescript app.get '/alias-for-home', (req,res,next) -> req.templateData = { weDidSomeCustomRendering: true }; var document = docpadInstance.getFile({relativePath:'home.html.md'}); docpadInstance.serveDocument({document, req, res, next}); ``` [<br>](https://docpad.org/docs/showcase) # Command Line Interface * To discover what commands are available: ```bash docpad --help ``` * To create your website (if it doesn't already exist), watch for changes, and start the webserver, use: ``` docpad run ``` * To just generate your website from one of the existing skeletons, use: ``` docpad scaffold ``` * To just generate your compiled website, use: ``` docpad generate ``` * To just watch your website for changes and re-generate whenever a change is made, use: ``` docpad watch ``` * To just run the DocPad server to access your already generated website, use: ``` docpad server ``` * To render standalone files with DocPad programmatically (will output to stdout) ``` docpad render filePath ``` For example, to render a markdown file and save the result to an output file, we would use: ```bash docpad render inputMarkdownFile.html.md > outputMarkdownFile.html ``` * To render stdin with DocPad programmatically (will output to stdout) ```bash echo $content | docpad render sampleFileNameWithExtensions ``` For example, to render passed markdown content and save the result to a file, we would use: ```bash echo "**awesome**" | docpad render input.html.md > output.html ``` [<br>](https://docpad.org/docs/api) # Configuration ### Configuration Files <a href="#configuration-files" id="configuration-files"></a> The DocPad configuration file sits within the root of your DocPad project and is named as one of the following. Each name provides a special meaning. Here are the valid names: * `docpad.js` a Node JavaScript file, will generally look like: `module.exports = {/*the configuration*/}` * `docpad.json` a JSON file, does not allow functions, will generally look like: `{/*the configuration*/}` * `docpad.coffee` a Node CoffeeScript file, will generally look like: `module.exports = /*the configuration*/` * `docpad.cson` a [cson](https://github.com/bevry/cson) file, will generally look like: `/*the configuration*/` The advantage of `docpad.js` and `docpad.coffee` over `docpad.json` and `docpad.cson` is that they allow us to declare functions, as well as call functions. However, for instances where we cannot trust the contents of the configuration files you would want to use the `docpad.json` or `docpad.cson` as they can't do anything naughty. The advantage of `docpad.coffee` and `docpad.cson` over `docpad.js` and `docpad.json` is that they allow us to use the CoffeeScript syntax which is a lot more lenient. Generally, you'll usually find either a `docpad.coffee` file or a `docpad.cson` file. #### Available Configuration <a href="#available-configuration" id="available-configuration"></a> The following code is of a `docpad.coffee` file that contains every single configurable DocPad options - in reality you should only include the options that you have actually customised - using the following example for reference only. {% code title="docpad.coffee" %} ```coffeescript # DocPad Configuration docpadConfig = { # ================================= # Paths Configuration # Root Path # The root path of our our project rootPath: process.cwd() # default # Package Path # The project's package.json path # If it is a relative path, it will have the resolved `rootPath` prepended to it packagePath: 'package.json' # default # Config Paths # An array of paths that we try to extract our docpad configuration from configPaths: [ # default 'docpad.js' 'docpad.coffee' 'docpad.json' 'docpad.cson' ] # Plugin Paths # An array of special paths which to load single plugins from # (e.g., ['/a/path/to/a/docpad-plugin-special']) pluginPaths: [] # default # Plugins Paths # An array of paths which to load multiple plugins from pluginsPaths: [ # default 'node_modules' 'plugins' ] # Reload Paths # An array of special paths that when changes occur in, we reload our configuration reloadPaths: [] # default # Regenerate Paths # An array of special paths that when changes occur in, we regenerate our website regeneratePaths: [] # default # Regenerate Delay # The time (in milliseconds) to wait after a source file has # changed before using it to regenerate. Updating over the # network (e.g., via FTP) can cause a page to be partially # rendered as the page is regenerated *before* the source file # has completed updating: in this case increase this value. regenerateDelay: 100 # default # Out Path # Where should we put our generated website files? # If it is a relative path, it will have the resolved `rootPath` prepended to it outPath: 'out' # default # Src Path # Where can we find our source website files? # If it is a relative path, it will have the resolved `rootPath` prepended to it srcPath: 'src' # default # Documents Paths # An array of paths which contents will be treated as documents # If it is a relative path, it will have the resolved `srcPath` prepended to it documentsPaths: [ # default 'render' 'documents' ] # Files Paths # An array of paths which contents will be treated as files # If it is a relative path, it will have the resolved `srcPath` prepended to it filesPaths: [ # default 'static' 'files' 'public' ] # Layouts Paths # An array of paths which contents will be treated as layouts # If it is a relative path, it will have the resolved `srcPath` prepended to it layoutsPaths: [ # default 'layouts' ] # Ignore Paths # Can be set to an array of absolute paths that we should ignore from the scanning process ignorePaths: false # default # Ignore Hidden Files # Whether or not we should ignore files that start with a dot from the scanning process ignoreHiddenFiles: false # default # Ignore Common Patterns # Whether or not we should ignore commonly undesired files from the scanning process # (e.g., .DStore, thumbs.db, .git, files that start with a tilda, etc.) ignoreCommonPatterns: true # default # Ignore Custom Patterns # Can be set to a regex of custom patterns to ignore from the scanning process ignoreCustomPatterns: false # default # ================================= # Server Configuration # Port # Use to change the port that DocPad listens to # By default we will detect the appropriate port number for our environment # if no environment port number is detected we will use 9778 as the port number # Checked environment variables are: # - PORT - Heroku, Nodejitsu, Custom # - VCAP_APP_PORT - AppFog # - VMC_APP_PORT - CloudFoundry port: null # default # Max Age # The default caching time limit that is sent with the response to the client # Can be set to `false` to disable caching maxAge: 86400000 # default # Server Express # The Express.js instance that we want DocPad to use # If not set, we will create our own serverExpress: null # default # Server HTTP # The Node.js HTTP server instance that we want DocPad to use # If not set, we will create our own serverHttp: null # default # ================================= # Middleware Configuration # Which middlewares would you like us to activate # Setting `extendServer` to `false` will set all of these to `false` automatically # Extend Server # Whether or not we should extend the server with our custom middleware extendServer: true # default # The standard middlewares (bodeParser, methodOverride, Express router) middlewareStandard: true # default # The standard bodyParser middleware middlewareBodyParser: true # default # The standard methodOverride middleware middlewareMethodOverride: true # default # The standard Express router middleware middlewareExpressRouter: true # default # Our own 404 middleware middleware404: true # default # Our own 500 middleware middleware500: true # default # ================================= # Logging Configuration # Log Level # Up to which level of logging should we output logLevel: (if ('-d' in process.argv) then 7 else 6) # default # Logger # The caterpillar instance that we want to use # If not set, we will create our own logger: null # default # Growl # Whether or not we should display system notifications as things progress within DocPad growl: true # default # Catch Exceptions # Whether or not DocPad should catch uncaught exceptions catchExceptions: true # default # Report Errors # Whether or not we should report errors back to the DocPad Team reportErrors: process.argv.join('').indexOf('test') is -1 # default (don't enable if we are running inside a test) # Report Statistics # Whether or not we should report statistics back to the DocPad Team reportStatistics: process.argv.join('').indexOf('test') is -1 # default (don't enable if we are running inside a test) # Airbrake Token # The airbrake token we should use for reporting errors # By default, uses the DocPad Team's token airbrakeToken: null # default # MixPanel Token # The mixpanel token we should use for reporting statistics # By default, uses the DocPad Team's token mixpanelToken: null # default # ================================= # Other Configuration # Detect Encoding # Should we attempt to auto detect the encoding of our files? # Useful when you are using foreign encoding (e.g., GBK) for your files # Only works on unix systems currently (limit of iconv module) detectEncoding: false # Render Single Extensions # Whether or not we should render single extensions by default renderSingleExtensions: false # default # Render Passes # How many times should we render documents that reference other documents? renderPasses: 1 # default # Check Version # Whether or not to check for newer versions of DocPad checkVersion: false # default # Welcome # Whether or not we should display any custom welcome callbacks welcome: false # default # Prompts # Whether or not we should display any prompts prompts: false # default # Helper Url # Used for subscribing to newsletter, account information, and statistics, etc. helperUrl: 'https://docpad.org/helper/' # default # Safe Mode # If enabled, we will try our best to sandbox our template rendering so that they cannot modify things outside of them # Not yet implemented safeMode: false # default # Collections # A hash of functions that create collections collections: {} # default # Regenerate Every # Performs a regenerate every x milliseconds, useful for always having the latest data regenerateEvery: false # default # ================================= # Template Configuration # Template Data # Use to define your own template data and helpers that will be accessible to your templates # Complete listing of default values can be found here: http://docpad.org/docs/template-data templateData: # example # Specify some site properties site: # The production URL of our website url: "http://website.com" # The default title of our website title: "Your Website" # The website description (for SEO) description: """ When your website appears in search results in say Google, the text here will be shown underneath your website's title. """ # The website keywords (for SEO) separated by commas keywords: """ place, your, website, keywoards, here, keep, them, related, to, the, content, of, your, website """ # ----------------------------- # Helper Functions # Get the prepared site/document title # Often we would like to specify particular formatting to our page's title # we can apply that formatting here getPreparedTitle: -> # if we have a document title, then we should use that and suffix the site's title onto it if @document.title "#{@document.title} | #{@site.title}" # if our document does not have its own title, then we should just use the site's title else @site.title # Get the prepared site/document description getPreparedDescription: -> # if we have a document description, then we should use that, otherwise use the site's description @document.description or @site.description # Get the prepared site/document keywords getPreparedKeywords: -> # Merge the document keywords with the site keywords @site.keywords.concat(@document.keywords or []).join(', ') # ================================= # Plugin Configuration # Skip Unsupported Plugins # Set to `false` to load all plugins whether or not they are compatible with our DocPad version or not skipUnsupportedPlugins: true # default # Enable Unlisted Plugins # Set to false to only enable plugins that have been explicity set to `true` inside `enabledPlugins` enableUnlistedPlugins: true # default # Enabled Plugins enabledPlugins: # example # Disable the Pokemon Plugin pokemon: false # Enable the Digimon Plugin # Unless, enableUnlistedPlugins is set to false, all plugins are enabled by default digimon: true # Configure Plugins # Should contain the plugin short names on the left, and the configuration to pass the plugin on the right plugins: # example # Disable NIB within the Stylus Plugin stylus: useNib: false # ================================= # Event Configuration # Events # Allows us to bind listeners to the events that DocPad emits # Complete event listing can be found here: http://docpad.org/docs/events events: # example # Server Extend # Used to add our own custom routes to the server before the docpad routes are added serverExtend: (opts) -> # Extract the server from the options {server} = opts docpad = @docpad # ================================= # Environment Configuration # Locale Code # The code we shall use for our locale (e.g., `en`, `fr`, etc.) # If not set, we will attempt to detect the system's locale, if the locale can't be detected or if our locale file is not found for it, we will revert to `en` localeCode: null # default # Environment # Which environment we should load up # If not set, we will default the `NODE_ENV` environment variable, if that isn't set, we will default to `development` env: null # default # Environments # Allows us to set custom configuration for specific environments environments: # default development: # default # Always refresh from server maxAge: false # default # Only do these if we are running standalone via the `docpad` executable checkVersion: process.argv.length >= 2 and /docpad$/.test(process.argv[1]) # default welcome: process.argv.length >= 2 and /docpad$/.test(process.argv[1]) # default prompts: process.argv.length >= 2 and /docpad$/.test(process.argv[1]) # default # Listen to port 9005 on the development environment port: 9005 # example } # Export the DocPad Configuration module.exports = docpadConfig ``` {% endcode %} ### Environment Configuration File <a href="#environment-configuration-file" id="environment-configuration-file"></a> We also support `.env` environment configuration file, the format works like so: {% code title=".env" %} ``` KEY=VALUE KEY2=VALUE2 ``` {% endcode %} All key-value pairs are added to the `process.env` environment variable. This is useful for setting sensitive information, like API keys, database information, and so on. If you're using `.env` using for this purpose, be sure to add `.env` to your `.gitignore` file! ### Global Configuration File <a href="#global-configuration-file" id="global-configuration-file"></a> DocPad will also create a global configuration file located at `~/.docpad.cson` (or `~/Dropbox/.docpad.cson` if you have [Dropbox](http://j.mp/dropbox-bal) installed). The `~`indicates your home directory (e.g., `/Users/balupton`), not your project directory. This file is typically used to store information relating to your DocPad preferences, such as whether or not you have agreed to the [TOS](https://docpad.org/tos) and subscribed to our newsletter or not, however it can also be used to load in configuration that you would like applied to all of your projects. Normally, we wouldn't touch this file, however it is useful to on the odd occasion. For instance, if we wanted to set the default DocPad port to always be `9779` instead of `9778`, we can update the global configuration file to include: {% code title="docpad.coffee" %} ```coffeescript { port: 9779 } ``` {% endcode %} [<br>](https://docpad.org/docs/cli) # Events ### Using Events <a href="#using-events" id="using-events"></a> #### Event Handler Structure <a href="#event-handler-structure" id="event-handler-structure"></a> All DocPad events receive two arguments (both optional): 1. `opts`, a simple object containing any options that the event provides 2. `next`, a completion callback DocPad's events are fired in a *synchronous* (or *serial*) fashion. In other words, when the first event runs until finished, then the next event fires and runs until finished, and so on. *Asynchronous* code, however, has no implicit guarantees about the order of execution. It will fire the first event, and may then immediately fire the second event while the first is still running. That's why asynchronous code requires callbacks. When the first event is done, it will run the callback function it was invoked with. It's the callback's job to signal when it's okay to proceed to the next event. Node.js itself is built for asynchronous execution, so it's pretty common for Node.js programs to run asynchronously. Since DocPad's events are run synchronously, omitting the `next` callback is perfectly valid (even encouraged) if you're using DocPad in your own synchronous code. (Of course, you're free to write in whatever style works best for you! If you enjoy coding in the asynchronous style, the `next` callback is available for you.) #### Inside your Configuration File <a href="#inside-your-configuration-file" id="inside-your-configuration-file"></a> You can bind to events in your DocPad configuration file by adding them to the `events` property. **Example:** Let's use a `docpad.coffee` configuration file. Binding to the `serverExtend` event would look like so: ``` docpadConfig = # ================================= # DocPad Events # Here we can define handlers for events that DocPad fires # You can find a full listing of events on the DocPad Wiki events: # Server Extend # Used to add our own custom routes to the server before the docpad routes are added serverExtend: (opts) -> # Extract the server from the options {server} = opts docpad = @docpad # Perform our server extensions # ... # Export our DocPad Configuration module.exports = docpadConfig ``` The context (what `this`/`@` points to) of event handlers is a shared object between the event handlers that contains only the docpad instance variable. #### Inside your Plugins <a href="#inside-your-plugins" id="inside-your-plugins"></a> You can bind to events inside your DocPad plugin by just adding the event handler directly to your plugin's definition. As such, binding to the `render` event to render from one extension to the other would look like so: ``` # Export Plugin module.exports = (BasePlugin) -> # Define Plugin class RenderPlugin extends BasePlugin # ... # Render some content synchronously render: (opts) -> # Prepare {inExtension,outExtension,content} = opts docpad = @docpad # Perform our rendering # ... ``` The context (what `this`/`@` points to) of event handlers in your plugin will be your plugin's instance. ### Available Events <a href="#available-events" id="available-events"></a> Sorted by their flow of execution within DocPad #### `extendCollections` <a href="#extendcollections" id="extendcollections"></a> Called each time the configuration for DocPad reloads. Called after most of the configuration has loaded and when it is time to extend our collections. Use to create additional collections. **Examples:** * [Partials Plugin](https://github.com/docpad/docpad-plugin-partials) #### `extendTemplateData` <a href="#extendtemplatedata" id="extendtemplatedata"></a> Called each time the configuration for DocPad reloads. Called after most of the configuration has loaded and when it is time to extend our template data. **Options:** * `templateData` the object to inject your additions to Use to inject new template data variables and helpers into the template data. **Examples:** * [Services Plugin](https://github.com/docpad/docpad-plugin-services) * [Feedr Plugin](https://github.com/docpad/docpad-plugin-feedr) #### `docpadLoaded` <a href="#docpadloaded" id="docpadloaded"></a> Called each time the configuration for DocPad reloads. Called before `docpadReady` as we have to load the configuration in order to be ready. #### `docpadReady` <a href="#docpadready" id="docpadready"></a> Called once DocPad when DocPad is now ready to perform actions which is once it has finished initializing and loading its configuration. Partnered with the `docpadDestroy` event. #### `consoleSetup` <a href="#consolesetup" id="consolesetup"></a> Called once the command line interface for DocPad has loaded. **Options:** * `consoleInterface` the console interface instance we are using * `commander` the instance of [commander](https://github.com/visionmedia/commander.js) we are using Use to extend the console interface with additional commands. **Examples:** * [GitHub Pages Plugin](https://github.com/docpad/docpad-plugin-ghpages) #### `populateCollectionsBefore` <a href="#populatecollectionsbefore" id="populatecollectionsbefore"></a> Called just before we start to insert dynamic files into the database. Called before each generation, just before the `generateBefore` event. Partnered with the `populateCollections` event. #### `populateCollections` <a href="#populatecollections" id="populatecollections"></a> Called just after we've inserted dynamic files into the collections. Called before each generation, just before the `generateBefore` event. Partnered with the `populateCollectionsBefore` event. Use this for inserting your dynamic files into the database. **Examples:** * [Tumblr Importer Plugin](https://github.com/docpad/docpad-plugin-tumblr) #### `generateBefore` <a href="#generatebefore" id="generatebefore"></a> Called just before we start generating your project. Partnered with the `generateAfter` event. **Options:** * `reset` whether or not this is a partial- (`false`) or full-regeneration (`true`) * ~~`server`~~ Deprecated; use `getServer()` API method instead #### ~~`parseBefore`~~ <a href="#del-code-parsebefore-code-del" id="del-code-parsebefore-code-del"></a> Deprecated/removed since DocPad v6.58.0. See [issue #736](https://github.com/bevry/docpad/issues/736) for information. #### ~~`parseAfter`~~ <a href="#del-code-parseafter-code-del" id="del-code-parseafter-code-del"></a> Deprecated/removed since DocPad v6.58.0. See [issue #736](https://github.com/bevry/docpad/issues/736) for information. #### `conextualizeBefore` <a href="#conextualizebefore" id="conextualizebefore"></a> Called just before we start to contextualize all the files. Partnered with the `contextualizeAfter` event. Contextualizing is the process of adding layouts and awareness of other documents to our document. **Options:** * `collection` the collection we are working with * ~~`templateData`~~ Deprecated; use `extendTemplateData` event instead #### `contextualizeAfter` <a href="#contextualizeafter" id="contextualizeafter"></a> Called just after we've finished contextualize all the files. Partnered with the `conextualizeBefore` event. Contextualizing is the process of adding layouts and awareness of other documents to our document. **Options:** * `collection` the collection we are working with * ~~`templateData`~~ Deprecated; use `extendTemplateData` event instead #### `renderBefore` <a href="#renderbefore" id="renderbefore"></a> Called just before we start rendering all the files. Partnered with the `renderAfter` event. **Options:** * `collection` a [query-engine](https://github.com/bevry/query-engine) collection containing the models we are about to render * `templateData` the template data that will be provided to the documents #### `renderCollectionBefore` <a href="#rendercollectionbefore" id="rendercollectionbefore"></a> Triggered before a render collection is about to be rendered. Added by [Bruno Heridet](https://github.com/Delapouite) with [Pull Request #608](https://github.com/bevry/docpad/pull/608). **Options:** * `collection` a [query-engine](https://github.com/bevry/query-engine) collection containing the models we are about to render * `renderPass` which render pass is this render collection for? #### `renderCollectionAfter` <a href="#rendercollectionafter" id="rendercollectionafter"></a> Triggered before a render collection is about to be rendered. Added by [Bruno Heridet](https://github.com/Delapouite) with [Pull Request #608](https://github.com/bevry/docpad/pull/608). **Options:** * `collection` a [query-engine](https://github.com/bevry/query-engine) collection containing the models we are about to render * `renderPass` which render pass is this render collection for? #### `render` <a href="#render" id="render"></a> Called per document, for each extension conversion. Use to render one extension to another. **Options:** * `inExtension` the extension we are rendering from * `outExtension` the extension we are rendering to * `templateData` the template data that we will use for this document's rendering * `file` the model instance for the document we are rendering * `content` the current content that this document contains, you shall overwrite this option with any updates you do **Notes:** The file `blah.html.md.eco` will call trigger this event twice. The first time for the `eco` to `md` conversion. The second time for the `md` to `html`conversion. **Example:** You would check the `inExtension` and `outExtension` options to make sure we only apply our rendering for the desired extension conversions. To apply the rendering, we would write our result back to `opts.content`. For example here is a render event handler that will convert the content of files to upper case when named like `file.txt.captialize|uppercase|upper`: ```coffeescript render: (opts) -> # Prepare {inExtension,outExtension,templateData,file,content} = opts docpad = @docpad # Render if applicable if inExtension in ['capitalize','uppercase','upper'] and outExtension in ['txt'] opts.content = content.toUpperCase() # your conversion to be saved ``` #### `renderDocument` <a href="#renderdocument" id="renderdocument"></a> Called per document, after all the extensions have been rendered. Use to perform transformations to the entire document. **Options:** * `extension` the resulted extension for our document * `templateData` the template data that we will use for this document's rendering * `file` the model instance for the document we are rendering * `content` the current content that this document contains, you shall overwrite this option with any updates you do **Notes:** It is also called for each of the layout rendering for the document, as well as for each [render pass](https://docpad.org/docs/faq#what-are-render-passes), as such care should be taken with ensuring your transformation does not re-transform an already transformed part. **Example:** [The Pygments Plugin](https://github.com/docpad/docpad-plugin-pygments) more or less uses this event to search for all `<code>` HTML elements that have the CSS class `highlight` (e.g., `<code class="highlight">`) and replaces the element with one that has been syntax highlighted by the popular [pygments](http://pygments.org/) syntax highlighting engine. #### `renderAfter` <a href="#renderafter" id="renderafter"></a> Called just just after we've rendered all the files. Partnered with the `renderBefore` event. **Options:** * `collection` a [query-engine](https://github.com/bevry/query-engine) collection containing the models we've rendered #### `writeBefore` <a href="#writebefore" id="writebefore"></a> Called just before we start writing all the files. Partnered with the `writeAfter` event. **Options:** * `collection` a [query-engine](https://github.com/bevry/query-engine) collection containing the models we are about to write * `templateData` the template data that was provided to the documents #### `writeAfter` <a href="#writeafter" id="writeafter"></a> Called just just after we've wrote all the files. Partnered with the `writeBefore` event. **Options:** * `collection` a [query-engine](https://github.com/bevry/query-engine) [collection](https://github.com/bevry/query-engine/wiki/Using) containing the models we are about to render #### `generateAfter` <a href="#generateafter" id="generateafter"></a> Called just after we've finished generating your project. Partnered with the `generateBefore` event. #### `generated` <a href="#generated" id="generated"></a> Called just after the initial generation has completed. #### `serverBefore` <a href="#serverbefore" id="serverbefore"></a> Called just before we start setting up the server. Partnered with the `serverAfter` event. #### `serverExtend` <a href="#serverextend" id="serverextend"></a> Called just while we are setting up the server, and just before the DocPad routes are applied. Use to extend the server with routes that will be triggered before the DocPad routes. **Options:** * `server` and `serverExpress` are the [Express.js](http://expressjs.com/) server instance we are using * `serverHttp` is the raw Node.js HTTP server we are using * `express` is the Express module we are using #### `serverAfter` <a href="#serverafter" id="serverafter"></a> Called just after we finished setting up the server. Use to extend the server with routes that will be triggered after the DocPad routes. **Options:** * `server` and `serverExpress` are the [Express.js](http://expressjs.com/) server instance we are using * `serverHttp` is the raw Node.js HTTP server we are using * `express` is the Express module we are using #### `docpadDestroy` <a href="#docpaddestroy" id="docpaddestroy"></a> Called when it is time for DocPad to shutdown. Partnered with the `docpadReady` event. Use this to shutdown anything inside your plugins, close all connections, file system handlers, files, etc. # Meta Data ### Introduction <a href="#introduction" id="introduction"></a> Meta data goes at the top of documents, and is defined by any character that repeats 3 or more times. For example, `---` is the most common usage, but you can also use `###` or whatever repeats 3 or more times. By default, we parse the meta data with [YAML](http://www.yaml.org/) but you can also use [CSON](https://github.com/bevry/cson) by doing `--- cson` instead. An example document that uses meta data will look like this: ``` --- title: "Example Document" layout: "default" --- My example document content ``` ### Special Meta Data <a href="#special-meta-data" id="special-meta-data"></a> #### For Files & Documents <a href="#for-files-documents" id="for-files-documents"></a> **title** The title for the document. Useful for headings. **layout** Tells DocPad what layout to use from the `layouts` folder. Layout files can use other layouts for advanced layout nesting. There is no default value. Layouts may have a layout called "default", but that is just a naming choice, rather than an implicit default. **name** Defaults to the `filename`. The name of the document. Useful for listings. **date** Defaults to `mtime`. Useful for setting a custom date via your documents meta data. **slug** Defaults to a slugified version of the `relativeBase`. Appears deprecated in favour of `url`. **url** The URL that you would like to use as the primary URL for the document. When a user accesses a document via a secondary URL, the user will be redirected to the primary URL automatically. **urls** The secondary URLs for a document. It can be a comma separated values list, or an array of values. **ignored** Defaults to `false`. If set to `true`, the document will not be parsed. Useful for draft documents. **standalone** Defaults to `false`. If set to `true`, when a change is detected for the document, we will only regenerate this document and not anything else (e.g., documents with `referencesOthers` set to `true`). #### For Documents <a href="#for-documents" id="for-documents"></a> **referencesOthers** Defaults to `false`. If set to `true`, this document will be regenerated when a change occurs in another document. It is automatically set to `true`whenever a template helper is called that references another document. This makes so for instance on a blog listing page, when a blog post is changed, we will also regenerate the listing as well as the blog post. **tags** Defaults to `[]`. Tags can be a comma separated values list, or an array of values. While DocPad doesn't use tags for anything specifically, it is nice to have it handled uniformly across websites without you having to do it yourself. **dynamic** Defaults to `false`. If set to `true`, the document will be re-rendered on each request. This also adds the [`req`](http://expressjs.com/api.html#request) object to the template data. ### Special Attributes <a href="#special-attributes" id="special-attributes"></a> #### For Files & Documents <a href="#for-files-documents" id="for-files-documents"></a> **id** The unique document identifier. Defaults to the [cid](http://backbonejs.org/#Model-cid). When we get the `relativePath`, we set the `id` to that instead. **basename** The file's name without the extension. **extension** The file's last extension (e.g., will be set to `eco` for the file `hello.md.eco`). **outExtension** The extension used for the output file. Same method as `extension` however it takes layouts into account as well. **extensions** The file's extensions as an array (e.g., will be set to `["md","eco"]` for the file `hello.md.eco`). **filename** The file's name with the extension. **path** The full path of our source file. **outPath** The full path of our output file. **dirPath** The full directory path of our source file. **outDirPath** The full directory path of our output file. **outFilename** The file's name with the output extension. **relativePath** The relative path of our source file. **relativeOutPath** The relative path of our output file. **relativeDirPath** The relative directory path of our source file. **relativeOutDirPath** The relative directory path of our output file. **relativeBase** The relative path of our source file without the file's extension. **contentType** The MIME content-type for the source file. **outContentType** The MIME content-type for the output file. **ctime** The `Date` object for when this file was created. **mtime** The `Date` object for when this file was modified. **encoding** The encoding of the file. Either `binary` or `utf8`. **source** When `encoding` isn't `binary`, this is set to the raw contents of the file, stored as a string. **content** When `encoding` isn't `binary`, this is set to the contents of the file, stored as a string. This is used internally during the rendering process, **end-users should never use this property, instead they should either `source` or `contentRendered` depending on the use case.** ### For Documents <a href="#for-documents" id="for-documents"></a> **write** Defaults to `true`. Whether or not this document should be written to the output directory. **render** Defaults to `true`. Whether or not this document should be rendered. **header** The file meta data (header) in String format before it has been parsed. **parser** Defaults to `yaml`. The parser we used to parse the document's meta data header. **body** The file content (without the meta data header) before we've rendered it. **rendered** Defaults to `false`. Set to `true` once we have been rendered. **contentRendered** The rendered content (after is has been wrapped in the layouts). **contentRenderedWithoutLayouts** The rendered content (before being wrapped by the layouts). ### Methods <a href="#methods" id="methods"></a> #### For Everything <a href="#for-everything" id="for-everything"></a> [Refer to the Backbone Model Documentation](http://backbonejs.org/#Model) #### For Files & Documents <a href="#for-files-documents" id="for-files-documents"></a> **toJSON()** Same as the [Backbone Model toJSON](http://backbonejs.org/#Model-toJSON), but will also call `toJSON` on the original meta data to `meta` within the result. **getMeta()** Get the meta data [Backbone Model](http://backbonejs.org/#Model) for the file. **setMeta(attrs)** Same as the [Backbone Model Set](http://backbonejs.org/#Model-set), but for the meta data Model. **setDefaults(attrs)** Same as the [Backbone Model Set](http://backbonejs.org/#Model-set), but will only set attributes that haven't already been set to something. **setMetaDefaults(attrs)** Same as the [Backbone Model Set](http://backbonejs.org/#Model-set), for the meta data but will only set the meta data Model attributes that haven't already been set to something. **setData(data)** Used for setting data of a virtual file (a file that does not have physical path). **getData()** Used for getting the data of a virtual file (a file that does not have physical path). **setBuffer(buffer)** Used for setting the source [buffer](http://nodejs.org/api/buffer.html). **getBuffer()** Used for getting the source [buffer](http://nodejs.org/api/buffer.html). **setStat(stat)** Used for setting the [stat](http://nodejs.org/api/fs.html#fs_class_fs_stats) of the file. **getStat()** Used for getting the [stat](http://nodejs.org/api/fs.html#fs_class_fs_stats) of the file. **getContent()** Used for getting the parsed source content or the buffer instance if it is a binary file. **getOutContent()** Used for getting the rendered content. **isText()** Is the file a text file? **isBinary()** Is the file a binary file? **setUrl(url)** Set the primary URL for the file. **addUrl(url)** Set a secondary URL for the file. **removeUrl(url)** Remove a URL for the file. **getPath(relativePath, parentPath)** Gets a path relative to the file. #### For Documents <a href="#for-documents" id="for-documents"></a> **referencesOthers(flag?=true)** Whether or not this document references another document. Sets the `referencesOthers` flag. # Sequence Flow ### Legend <a href="#legend" id="legend"></a> ``` : Object/Area > method < procedure >> background method << background procedure ? condition ``` ### Run Action <a href="#run-action" id="run-action"></a> ``` : Interface > command : Core > run > server > generate > createProgress > createRengerateTimer > generatePrepare ? if reset is true ? if source directory doesn't exist < error > resetCollections < reset database > populateCollections > parseDirectory documentsPath > parseDirectory filesPath > parseDirectory layoutsPaths > emitSerial "populateCollectionsBefore" : Tumblr Plugin > fetchTumblrData < json data from tumblr api < add each tumblr post into docpad database < use all models ? if reset is false < use changed models > emitSerial "generateAfter" > generateLoad > loadFiles opts.collection < add references and layout children to opts.collection > generateRender > contextualizeFiles > emitSerial "contextualizeBefore" > file.contextualize < meta data normalized < layout determined > emitSerial "conextualizeAfter" > renderFiles > emitSerial "renderBefore" > renderCollection(referencesOthers:false) + renderCollection(referencesOthers:true) < for each render pass > file.render > emitSerial "render" > emitSerial "renderDocument" > emitSerial "renderAfter" > writeFiles > generatePostpare > emitSerial "generateAfter" > watch >> watchr.watch config.reloadPaths >> docpad.load >> docpad.generate reset:true >> watchr.watch config.regeneratePaths >> docpad.generate reset:true >> watchr.watch config.srcPath >> docpad.generate ``` # Template Data & Helpers ### Standard Template Data <a href="#standard-template-data" id="standard-template-data"></a> * `site` — an object of several site-specific properties, contains: * `date` — a JavaScript date object for the time that the website was last generated * `document` — a JavaScript Object containing the serialised values of our `documentModel` (e.g., `documentModel.toJSON()`) * `req` — dynamic documents will also have this available to the, it is a reference to the current request object created by the [ExpressJS](http://expressjs.com/) framework * `content` — when rendering layouts the `content` template data variable contains the contents of the rendered child content to be injected into the current layout for rendering ### Standard Template Helpers <a href="#standard-template-helpers" id="standard-template-helpers"></a> * `include(relativePath)` return the content of another file at the given path * `getEnvironment()` — a string of the current environment(s) we are running under * `getEnvironments()` — an array of the current environments we are running under * `referencesOthers()` — when called, will set the document's `referenceOthers` [meta data](/core/meta-data) property to `true` * `getDocument()` — a reference to the current document we are rendering, documents are defined by the [Document Class](https://github.com/bevry/docpad/blob/master/src/lib/models/document.coffee) which extends the [File Class](https://github.com/bevry/docpad/blob/master/src/lib/models/file.coffee) which extends a [Backbone Model](http://backbonejs.org/#Model) * `getBlock(blockName)` — valid block names are: * `scripts` — a collection of scripts to be outputted * `styles` — a collection of styles to be outputted * `meta` — a collection of meta to be outputted * `getPath(path,parentPath)` get a path with respect to the path of the current document #### Querying <a href="#querying" id="querying"></a> * `getDatabase()` — a [Query-Engine](https://github.com/bevry/query-engine) collection of all our documents * `getCollection(collectionName)` — a [Query-Engine](https://github.com/bevry/query-engine) collection of a particular sub collection, built in collections are: * `documents` — for all documents * `files` — for all files * `layouts` — for all files * `html` — for all documents and files that result in an HTML file * `stylesheet` — for all stylesheet files (includes stylesheet pre-processor files) * `getFiles(query, sorting, paging)` get all files that match the arguments, caches the result collection * `getFile(query, sorting, paging)` get a single file that matches the arguments * `getFilesAtPath(path, sorting, paging)` get a file at the given path, path is processed through `getPath` * `getFileAtPath(path, sorting, paging)` get a single file at the given path, path is processed through `getPath` * `getFileById(id, sorting, paging)` get a single file that has the specified id # Extending Here are all the different ways that DocPad can be extended. ### Module <a href="#module" id="module"></a> DocPad can also be used as a module in other systems * [Browse DocPad's API](/core/api) ### Configuration Files <a href="#configuration-files" id="configuration-files"></a> Configuration files allow you to apply site specific extensions and configurations * [How to use the configuration file](/core/config) * [Learn the available events](/core/events) ### Plugins <a href="#plugins" id="plugins"></a> Plugins provide extra functionality to DocPad, and can be re-used across Skeletons * [Find existing plugins](/community/plugins) * [Learn to write plugins](/extend/plugin-write) * [Learn the available events](/core/events) ### Projects <a href="#skeletons" id="skeletons"></a> Projects are essentially re-usable websites/projects/webapps that have been created with DocPad * [Find existing DocPad projects](https://docpad.bevry.me/projects) * Get your project listed by adding the `docpad-project` topic to its GitHub repository [<br>](https://docpad.org/docs/template-data) # Write a Plugin ### Getting Started <a href="#getting-started" id="getting-started"></a> 1. Inside your DocPad website directory, create a directory called `plugins` (i.e. `yourwebsite/plugins`) 2. Inside your new plugins directory, create the directory for your plugin (i.e. `yourwebsite/plugins/yourpluginname`) 3. Inside your new plugin directory, run the following commands to clone out the [example plugin](https://github.com/docpad/docpad-plugin-yourpluginname) that we will use as our base: ```bash git init git remote add base https://github.com/docpad/docpad-plugin-yourpluginname.git git pull base master npm run our:setup # installs dependencies, and prepares the docpad dependency for development npm run our:commpile # compile your plugin ``` You will now find several files. An important thing to note about the `package.json` file is that our plugin starts with the version `2.0.0`. This is because v2 plugins are compatible for with DocPad v6, whereas v1 plugins are compatible with DocPad v5. [This is currently a necessary convention that you must follow.](https://github.com/docpad/docpad/issues/691) The `source/index.coffee` file is the logic for our plugin. It's current contents will uppercase all documents with `.uc` or `.uppercase`extension. The simplest form of this file (which wouldn't perform anything) would be: {% code title="source/index.coffee" %} ```coffeescript # Export Plugin module.exports = (BasePlugin) -> # Define Plugin class YourpluginnamePlugin extends BasePlugin # Plugin name name: 'yourpluginname' ``` {% endcode %} A more verbose form of this would be: {% code title="source/index.coffee" %} ```coffeescript # Export a function that will accept the BasePlugin class from DocPad and then will return our own class that will extend it. module.exports = (BasePlugin) -> # Create and return our own class that extends the BasePlugin class class YourpluginnamePlugin extends BasePluginource name: 'yourpluginname' # The rest of your plugin definition goes here # ... ``` {% endcode %} Extending the [BasePlugin](https://github.com/docpad/docpad/blob/master/src/lib/plugin.coffee) class is important as it provides some of the tucked away magic for our plugins, such as automatically listening for events when a plugin method of the event name is defined. [You can discover the plugin events available to you on the Events Page.](https://docpad.org/docs/events) If you prefer to write your plugins with ES6 JavaScript, you can do it like so: {% code title="source/index.js" %} ```javascript // Export Plugin module.exports = function (BasePlugin) { // Define Plugin return class YourpluginnamePlugin extends ({ // Plugin name get name () { return 'yourpluginname' } // Initial plugin configuration get initialConfig () { return {} } }); }; ``` {% endcode %} If you prefer to write your plugins with ES5 JavaScript, you can use the `BasePlugin.extend({})` method like so: {% code title="source/index.js" %} ```javascript // Export Plugin module.exports = function (BasePlugin) { // Define Plugin return BasePlugin.extend({ // Plugin name name: 'yourpluginname' }); }; ``` {% endcode %} ### Types of plugins <a href="#types-of-plugins" id="types-of-plugins"></a> #### Renderers <a href="#renderers" id="renderers"></a> Renderers are used to convert one particular type of text format, to another type, or rather something to something else. DocPad will perform these conversions from one format to another by triggering the `render` event. A plugin can hook into this event by adding the `render` function inside it. * [Here is the plugin file of an example plugin that performs the synchronous conversion of transforming the content of `txt` files that have the extra `uc` or `uppercase` extension to upper case.](https://github.com/docpad/docpad-plugin-yourpluginname/blob/master/source/index.coffee) * [Here is the plugin file of the coffeekup plugin that accepts configuration and performs and asynchronous conversion.](https://github.com/docpad/docpad-plugin-coffeekup/blob/master/source/index.coffee) An important thing to note about the rendering process is that DocPad knows when and how to call the render event based on the documents extensions. For instance, the document `document.html.md.eco` will have two render events fire. The first render event will contain the `inExtension` as `eco`, and the `outExtension` as `md`. The second render event will contain the `inExtension` as `md`, and the `outExtension` as `html`. This is why generally in our plugins we want to check the values of `inExtension` and `outExtension` to make sure our plugin is performing the correct render. #### Other types <a href="#other-types" id="other-types"></a> Plugins of other types are generated in the same way as Renderers, they simply aim to achieve different results. While Renderers primarily use the `render` event to trigger their behaviour other plugin types use a variety of events such as `writeBefore` and `parseAfter` to alter the creation of documents and add additional functionality. [Click here for more information on event types](/core/events) ### Making your Plugin Yours <a href="#making-your-plugin-yours" id="making-your-plugin-yours"></a> Probably the first thing you want to do is to change the name and description of your plugin. There are several spots you would want to do this: * The filenames in `src` * The classname and plugin name in `src/yourpluginname.plugin.coffee` * Various properties inside `package.json` * The heading and description inside `README.md` Once you update your `package.json` file with the new values, you would want to run `npm run our:release:prepare` which will also compile your plugin's meta files with [projectz](https://github.com/bevry/projectz), which is very useful for automatically updating your `README.md` and `LICENSE.md` files with the latest details for your `package.json` file. ### Testing your Plugin <a href="#testing-your-plugin" id="testing-your-plugin"></a> For testing our plugins, we will take note of the following files: ``` source/ test.coffee tester.coffee test/ out-expected/ ... src/ render/ ... package.json (optional) ``` **source/test.\*** This file is optional, but is useful for running tests against multiple configurations. For example, the [paged plugin's customisations](https://github.com/docpad/docpad-plugin-paged/blob/master/source/test.coffee) allows it to test its compatibility with other DocPad plugins. If you require such functionality, you can get started with something like this: ```javascript # Test our plugin using DocPad's Testers require('docpad-plugintester').test({testerClass: 'RendererTester', pluginPath: __dirname+'/..'}) ``` **source/tester.\*** This file is optional but is essential if you want to tell DocPad to load additional plugins as well as yours, or if you need to do advanced configuration of the test environment. The file exports a class that will be used to test your plugin. For now there's just the one tester type to extend from, `RendererTester`which by default runs your plugin against a folder of documents and compares the output to the contents of the `out-expected` folder. This is all you'll need for most plugins as we're only really concerned about the input and output of our plugins. **test/package.json** This file is optional but is essential if you want your test site require other plugins than just your one. The [Text Plugin](https://github.com/docpad/docpad-plugin-text) is a great example of this, you can find its [test site's package.json file here](https://github.com/docpad/docpad-plugin-text/blob/master/test/package.json). #### Writing the tests <a href="#writing-the-tests" id="writing-the-tests"></a> DocPad's `RendererTester` will setup an instance of DocPad using the configuration specified in your tester above, it will then generate a site using the documents in the `test/source/render` folder and compare the results with the files in the `test/out-expected` folder. This way you can quickly and easily test how documents in a site are handled by your plugin. #### Running the tests <a href="#running-the-tests" id="running-the-tests"></a> To run the full test suite, including compilation and meta updates, you would run: ```bash npm run our:release:prepare ``` Which will output something like: ``` > docpad-plugin-yourpluginname@2.0.0 test /Users/balupton/Projects/docpad-extras/plugins/yourpluginname > node ./out/yourpluginname.test.js yourpluginname yourpluginname ➞ create yourpluginname ➞ create ✔ yourpluginname ➞ load plugin yourpluginname yourpluginname ➞ load plugin yourpluginname ✔ yourpluginname ➞ generate yourpluginname ➞ generate ➞ action yourpluginname ➞ generate ➞ action ✔ yourpluginname ➞ generate ➞ results yourpluginname ➞ generate ➞ results ✔ yourpluginname ➞ generate ✔ yourpluginname ➞ server yourpluginname ➞ server ✔ yourpluginname ➞ finish up yourpluginname ➞ finish up ✔ yourpluginname ✔ 6/6 tests ran successfully, everything passed OK ``` Writing good unit tests is hard, but just try to cover all the possible inputs and expected outputs for your plugin and you will be making a good start. #### Linking DocPad <a href="#linking-docpad" id="linking-docpad"></a> If you are working on a development copy of DocPad, you can use it instead by running the following inside the DocPad instance directory: ```bash npm run our:release:prepare npm link ``` Then inside your plugin, run: ```bash npm link docpad npm run our:release:prepare ``` ### Maintenance <a href="#maintenance" id="maintenance"></a> If your plugin becomes popular with the DocPad community, you will have the option of making it an official plugin. This means: 1. Transferring it to the DocPad GitHub Organisation so that it can be maintained by the DocPad Extras Team 2. Running `npm owner add bevryme` in your plugin directory to give the DocPad Core Team publishing rights 3. The Core Team can then give publish rights to whomever from the Extra Team wants to take accountability for the plugin 4. The Extras Team can then alert the maintainers of the plugin of things that need doing (preferably via a pull request) so the maintainers can just merge and publish # Contribute ### Bevry <a href="#bevry" id="bevry"></a> For the most part, DocPad inherits from the [Bevry Community's Contribution Guide](/community/contribute), with the following exceptions. ### Setup <a href="#setup" id="setup"></a> To get started with developing and contributing code, you must first setup your project for development. #### Setup the DocPad core for development <a href="#setup-the-docpad-core-for-development" id="setup-the-docpad-core-for-development"></a> To setup a development environment for contributing to the DocPad core follow these steps: 1. Fork the repository of the DocPad Core: <https://github.com/docpad/docpad> 2. Clone your fork to your machine then `cd` into it 3. Run `npm run prepare` to install any missing dependencies 4. Run `npm run compile` to compile the project 5. Run `npm test` to test the project 6. Run `npm link` to make this development instance of the projects available to other projects (via `npm link docpad`) #### Setup a DocPad plugin for development <a href="#setup-a-docpad-plugin-for-development" id="setup-a-docpad-plugin-for-development"></a> To setup a development environment for contributing to a plugin follow these steps: 1. Ensure you have DocPad setup for development, by running the DocPad core instructions above 2. Fork the repository of the DocPad plugin you wish to edit 3. Clone your fork to your machine then `cd` into it 4. Run `npm link docpad` to link our local development instance of DocPad that we setup earlier to our DocPad plugin 5. Run `cake install` to install any missing dependencies 6. Run `cake compile` to compile the project 7. Run `cake test` to test the project 8. Run `npm link` to make this development instance of the project available to other projects (via `npm link docpad-plugin-PLUGINNAME`) # Participate This page will talk about being a developer for DocPad and what is involved. This guide is also a bit out of date, check out the new [Contributing Guide](/community/contribute) for the latest instructions. ### Who? What? Why? <a href="#who-what-why" id="who-what-why"></a> Anyone can be a developer for DocPad, this is because DocPad is entirely open-source, meaning anyone can browse, edit, and share the source-code of DocPad. The source-code is like the original code, the code that developers write to make things happen. So what is a developer? A developer can be whatever you want it to be! But I guess it is just someone who participates in the community, the growth, and direction DocPad is going. Naturally, a lot of people end up becoming developers without realising, as their involvement with DocPad increases, so does their amplitude to the commitment to DocPad and its success. For a lot of developers, DocPad's success = your success. ### How to participate as a developer? <a href="#how-to-participate-as-a-developer" id="how-to-participate-as-a-developer"></a> #### Issue Tracker <a href="#issue-tracker" id="issue-tracker"></a> The best way to participate is to be active on the [Issue Tracker](https://docpad.org/issues). Anything that needs doing for DocPad is logged there. Batches of work are split into monthly sprints called [Milestones](https://github.com/docpad/docpad/milestones). Issues are given a type, priority, and status (called buckets). Every issue is great for community participation, however issues with the label `discussion` are actively and urgently seeking developer feedback - so discuss those issues first! Any feedback would be great. Issues with the label `patches welcome` are issues which you can start implementing/coding up yourself, once you are done, submit a [pull request](https://help.github.com/articles/about-pull-requests/) back to the original DocPad project and we'll review your changes and provide feedback :-) #### Contribute Code <a href="#contribute-code" id="contribute-code"></a> If you've found a bug in DocPad, or want to add a new feature yourself. You can get hacking away at the source code, and submit a pull request to get your changes back into the official repository. [You can read more about this on the Contributing Guide here](/community/contribute). #### Discuss <a href="#discuss" id="discuss"></a> As DocPad developers are spread across the entire world, arranging a time for everyone to get chatting together is quite hard. However, that doesn't mean we don't try. #### Priority Focus <a href="#priority-focus" id="priority-focus"></a> Each month, we do a sprint bundled with new features from the roadmap and bugs from the issue tracker. We will always aim to get high priority bugs fixed and released as soon as possible. Once the bugs are all done, then we focus on the new features. When a feature is done, we release it to the public right away and then test and validate its value to the community. Once a feature has been proven to be valuable, we close it. You can read more about this process in the book [The Lean Startup](http://theleanstartup.com/). **On fixing bugs first** The focus on "bugs first, features later" is to ensure that the users of DocPad remain happy. Even though the developers may feel a new feature is crucial to DocPad's success, bugs are very horrible experiences for the existing users. Each day a bug is out in the code base, that is creating negative experiences, and a negative impression of the DocPad project and the DocPad community. Fixing bug's first is essential for having a happy community. **Implement and release tasks independently of each other** As we use the amazing git technology, there is a thing called branching, each new task (feature, bug, etc.) to be done should be implemented in its own branch. This prevents the feature from interfering with other features while you work on it. Once the feature is stable, a DocPad maintainer will pull it with the latest master branch and make sure it is still stable, then merge it into master branch and perform a release. This allows us to implement and release tasks independently on each other. So developers get immediate feedback, and users get immediate results - without any waiting! yay! # Plugins Here's a list of all available DocPad plugins. If you've created a plugin, be sure to include it in this listing! :) ### Installing <a href="#installing" id="installing"></a> To install a plugin, run `docpad install #{thePluginName}` inside your project directory. As an example, to install the [eco](https://github.com/docpad/docpad-plugin-eco/) plugin, you would run `docpad install eco` To uninstall a plugin, run `docpad uninstall #{thePluginName}` inside your project directory. In older versions of DocPad, you would run `npm install --save docpad-plugin-#{thePluginName}` to install, and `npm uninstall --save docpad-plugin-#{thePluginName}` to uninstall. ### Plugin Listing <a href="#complete-plugin-listing" id="complete-plugin-listing"></a> Complete listings of DocPad plugins can be found at: * [All GitHub projects that have the `docpad-plugin` tag](https://github.com/search?q=topic%3Adocpad-plugin\&type=Repositories) * [All NPM packages that have the `docpad-plugin` tag](https://www.npmjs.com/search?q=keywords:docpad-plugin) Below is a curated listing of plugins. ### Renderers <a href="#renderers" id="renderers"></a> These are plugins that add support for extra markups and languages to DocPad: #### Writing Markups <a href="#writing-markups" id="writing-markups"></a> * [marked](https://github.com/docpad/docpad-plugin-marked/) - Supports [Markdown](http://daringfireball.net/projects/markdown/basics) to HTML `.html.(md|markdown)` via [marked](https://github.com/chjj/marked) * [orgmode](https://bitbucket.org/bgschaid/docpad-plugin-orgmode/) - Supports converting [org-mode](http://orgmode.org/) to HTML `.html.org` via [org-js](https://github.com/mooz/org-js) * [textile](https://github.com/Greduan/docpad-plugin-textile) - Supports [Textile](https://www.npmjs.com/package/textile-js) to HTML `.html.textile` * [markit](https://github.com/tbusser/docpad-plugin-markit) - Supports [Markdown](http://daringfireball.net/projects/markdown/basics) to HTML `.html.(md|markdown)` via [markdown-it](https://github.com/markdown-it/markdown-it) * [asciidoc](https://github.com/fboulay/docpad-plugin-asciidoc) - Supports [Asciidoc](http://asciidoctor.org/docs/what-is-asciidoc/) to HTML `.html.adoc` via [asciidoctor.js](https://github.com/asciidoctor/asciidoctor.js) #### Data Markups <a href="#data-markups" id="data-markups"></a> * [cson](https://github.com/docpad/docpad-plugin-cson/) - Supports [CSON](https://github.com/bevry/cson) to JSON `.json.cson` * [yaml](https://github.com/jeremyfa/docpad-plugin-yamljs) - Supports [YAML](http://en.wikipedia.org/wiki/YAML) to JSON `.json.(yaml|yml)` and JSON to YAML `.(yml|yaml).json` #### CSS Pre-Processors <a href="#css-pre-processors" id="css-pre-processors"></a> * [less](https://github.com/docpad/docpad-plugin-less/) - Supports [LessCSS](http://lesscss.org/) to CSS `.css.less` * [roole](https://github.com/georgeosddev/docpad-plugin-roole) - Supports [Roole](http://roole.org/) to CSS `.css.roo` * [sass](https://github.com/docpad/docpad-plugin-sass/) - Supports [SCSS and SASS](http://sass-lang.com/) to CSS (includes [compass](http://compass-style.org/) support) `.css.(sass|scss)` * [nodesass](https://github.com/jking90/docpad-plugin-nodesass) - Supports [SCSS](http://sass-lang.com/) to CSS (using [node-sass](https://github.com/andrew/node-sass)) `.css.scss` * [styl](https://github.com/docpad/docpad-plugin-styl/) - Supports [Styl](https://github.com/visionmedia/styl) to CSS `.css.styl` * [stylus](https://github.com/docpad/docpad-plugin-stylus/) - Supports [Stylus](http://learnboost.github.com/stylus/) to CSS `.css.(styl|stylus)` #### Javascript Pre-Processors <a href="#javascript-pre-processors" id="javascript-pre-processors"></a> * [coffeescript](https://github.com/docpad/docpad-plugin-coffeescript/) - Supports [CoffeeScript](http://coffeescript.org/) to JavaScript `.js.coffee` * [js2coffee](https://npmjs.org/package/docpad-plugin-js2coffee) - Supports JavaScript to CoffeeScript `.coffee.js` * [livescript](https://github.com/docpad/docpad-plugin-livescript/) - Supports [LiveScript](http://livescript.net/) to JavaScript `.js.ls` * [move](https://github.com/docpad/docpad-plugin-move) - Supports [Move](https://github.com/rsms/move) to JavaScript `.js.move` * [typescript](https://github.com/bpampuch/docpad-plugin-tsc) - Supports [TypeScript](http://www.typescriptlang.org/) to JavaScript `.js.ts` * [babel](https://github.com/williammalo/docpad-plugin-babel/) - Supports ES6 to JavaScript using [Babel](http://babeljs.io/) `.js.babel` * [traceur](https://github.com/pflannery/docpad-plugin-traceur/) - Supports ES6 to JavaScript using [Traceur](https://github.com/google/traceur-compiler) `.js.traceur` #### HTML Pre-Processors <a href="#html-pre-processors" id="html-pre-processors"></a> **CoffeeScript Templating Engines** * [eco](https://github.com/docpad/docpad-plugin-eco/) - Supports [Eco](https://github.com/sstephenson/eco) to anything `.anything.eco` * [coffeekup](https://github.com/docpad/docpad-plugin-coffeekup/) - Supports [CoffeeKup](http://coffeekup.org/) to anything `.anything.coffee` * [html2coffee](https://github.com/docpad/docpad-plugin-html2coffee/) - Supports HTML to CoffeeKup `.coffee.html` * [coffeemugg](https://github.com/pflannery/docpad-plugin-coffeemugg) - Supports [CoffeeMugg](https://github.com/jaekwon/CoffeeMugg) to anything `.anything.coffee` * [hamlcoffee](https://github.com/ashnur/docpad-plugin-hamlcoffee/) - Supports [Haml Coffee](https://github.com/netzpirat/haml-coffee/) to HTML `.html.hamlc` * [teacup](https://github.com/hurrymaplelad/docpad-plugin-teacup/) - Supports [Teacup](http://goodeggs.github.io/teacup/) to HTML `.html.coffee` * [without](https://github.com/ukoloff/docpad-plugin-without) - Supports [withOut](https://github.com/ukoloff/without) to HTML `.html.coffee` **HAML-Like Templating Engines** * [haml](https://github.com/docpad/docpad-plugin-haml/) - Supports [Haml](http://haml.info/) to anything `.anything.haml` * [jade](https://github.com/docpad/docpad-plugin-jade/) - Supports [Jade](http://jade-lang.com/) to anything `.anything.jade` * [html2jade](https://github.com/docpad/docpad-plugin-html2jade) - Supports HTML to [Jade](http://jade-lang.com/) `.jade.html` **Moustache Templating Engines** * [handlebars](https://github.com/docpad/docpad-plugin-handlebars/) - Supports [Handlebars/Moustache](http://handlebarsjs.com/) to anything `.anything.(hb|hbs|handlebars)` * [hogan](https://github.com/docpad/docpad-plugin-hogan/) - Supports [Hogan/Mustache](http://twitter.github.io/hogan.js/) to anything `.anything.hogan` **Other Templating Engines** * [consolidate](http://github.com/robloach/docpad-plugin-consolidate) - Supports many template engines via [Consolidate.js](https://github.com/visionmedia/consolidate.js) * [slim](https://github.com/patocallaghan/docpad-plugin-slim) - Supports [Slim](http://slim-lang.com/) to anything `.anything.slim` * [swig](https://github.com/thisispete/docpad-plugin-swig) - Supports [Swig](https://github.com/paularmstrong/swig/) to HTML `.html.swig` * [htmlmin](http://github.com/robloach/docpad-plugin-htmlmin) - Supports minifying HTML with [HTML-Minifier](http://kangax.github.io/html-minifier/) `.html.anything` * [vash](https://github.com/harmony7/docpad-plugin-vash) - Supports [Vash](https://github.com/kirbysayshi/vash), an implementation of the [Razor template syntax](http://weblogs.asp.net/scottgu/archive/2010/07/02/introducing-razor.aspx) for JavaScript, to anything `.anything.vash` #### Languages <a href="#languages" id="languages"></a> * [cmds](https://github.com/pflannery/docpad-plugin-cmds/) - Adds some shell scripting fun. Supports `.anything.bash|.anything.sh|.anything.ps1|.anything.cmd` * [php](https://github.com/docpad/docpad-plugin-php) - Supports [PHP](http://php.net/) to anything `.anything.(php|phtml)` * [ruby](https://github.com/docpad/docpad-plugin-ruby) - Supports [Ruby](http://www.ruby-lang.org/) and [ERuby](http://en.wikipedia.org/wiki/ERuby) to anything `.anything.(ruby|erb)` ### Helpers <a href="#helpers" id="helpers"></a> These are plugins that add extra functionality to DocPad: * [addthis](https://github.com/mikeumus/docpad-plugin-addthis) - Adds the [AddThis](http://www.addthis.com/) toolbar into your project * [assets](https://github.com/mcdee/docpad-plugin-assets) - Change URL of asset files to contain hash of contents, allowing for effective caching whilst enabling cache busting when contents change * [associatedfiles](https://github.com/docpad/docpad-plugin-associatedfiles) - Lets you easily associate files to a particular document, and then grab the collection for them * [authentication](https://github.com/SteveMcArthur/docpad-plugin-authentication) - Handles authentication and login functionality via social login (ie google, facebook, twitter or github) for your docpad application. Protects pages from unauthenticated users. * [basicauth](https://github.com/mikeumus/docpad-plugin-basicauth) - Adds basic authentication to your project * [browserifybundles](https://github.com/docpad/docpad-plugin-browserifybundles) - Add configuration to your DocPad configuration file to create browserify bundles of your scripts * [browserifydocs](https://github.com/docpad/docpad-plugin-browserifydocs) - Browserify your documents by adding `browserify: true` to their meta data * [buildr](https://github.com/docpad/docpad-plugin-buildr/) - Supports bundling scripts and styles (including pre-processors like CoffeeScript, LESS, etc.) using [Buildr](https://github.com/balupton/buildr) * [cachr](https://github.com/docpad/docpad-plugin-cachr/) - Allows you to cache remote URLs locally from within your templates * [cleancss](https://github.com/docpad/docpad-plugin-cleancss) - Concatinate and minify CSS files with the `cleancss: true` meta data * [cleanurls](https://github.com/docpad/docpad-plugin-cleanurls/) - Adds support for URLs like `/blog/hello` as well as the original URL `/blog/hello.html` * [coffeelint](https://github.com/jking90/docpad-plugin-coffeelint) - Prints [coffeelint](http://www.coffeelint.org/) errors to the console * [csv](https://github.com/CycoPH/docpad-plugin-csv/) - Adds support for CSV data mapping. The comma seperated data files work just like a database, map from column 1 to column 2 * [datefromfilename](https://github.com/grassator/docpad-plugin-datefromfilename) - Automaticaly set the `date` meta-data property by determining it from the document's filename * [dateurls](https://github.com/mgroves84/docpad-plugin-dateurls/) - Adds support for date-based URLs like `/2013/04/27/hello.html` * [facebookcomments](https://github.com/mikeumus/docpad-plugin-facebookcomments) - Adds the [Facebook Comment Widget](https://developers.facebook.com/docs/reference/plugins/comments/) to your project * [feedr](https://github.com/docpad/docpad-plugin-feedr/) - Allows you to render remote feeds within your templates * [frontend](https://npmjs.org/package/docpad-plugin-frontend) - CSS and JavaScript asset manager and compiler for DocPad * [functions](https://www.npmjs.com/package/docpad-plugin-functions) - Start functions between DocPad events * [gist](https://github.com/docpad/docpad-plugin-gist/) - Pulls in gists into your document * [grunt](http://github.com/robloach/docpad-plugin-grunt) - Run [Grunt.js](http://gruntjs.com/) tasks when building with DocPad * [heapdumper](https://github.com/pflannery/docpad-plugin-heapdumper) - Generates a heapdump snapshot for chosen DocPad event(s), viewable in the Chrome profiler * [highlightjs](https://github.com/docpad/docpad-plugin-highlightjs/) - Adds [Highlight.js](https://github.com/isagalaev/highlight.js) syntax highlighting to code snippets * [ignoreincludes](https://github.com/rantecki/docpad-plugin-ignoreincludes) - Avoid writing include files to the `/out` directory * [jsexc](https://github.com/JeffreyZhao/docpad-plugin-jscexc) - Adds the ability to apply AOT compilation to JavaScript files * [jshint](https://github.com/jking90/docpad-plugin-jshint) - Prints [JSHint](http://www.jshint.com/) errors to the console * [jsonfragment](https://github.com/field/docpad-plugin-jsonfragment) - Writes each documents content without layout and its meta data into a separate `.json` file for quick loading via AJAX. * [livereload](https://github.com/docpad/docpad-plugin-livereload) - Automatically reloads the page whenever a regeneration is performed * [lunr](https://github.com/brockfanning/docpad-plugin-lunr) - Client-side full-text and faceted search using [Lunr.js](http://lunrjs.com/) * [menu](https://github.com/sergeche/docpad-plugin-menu) - Automatically generates menu from `/render` folder * [moment](https://github.com/brockfanning/docpad-plugin-moment) - Date formatting and access to [Moment.js](http://momentjs.com/) library * [nativecomments](https://github.com/docpad/docpad-plugin-nativecomments/) - Adds support for native comments to DocPad * [navlinks](https://github.com/lucor/docpad-plugin-navlinks) - Adds the ability to generate a navigation bar for documents with links to the next and previous document of a specified collection. * [paged](https://github.com/docpad/docpad-plugin-paged/) - Adds multiple page support to documents allowing you to render one document out to many pages * [partials](https://github.com/docpad/docpad-plugin-partials/) - Adds the ability to create re-usable partials for your templates within DocPad * [pygments](https://github.com/docpad/docpad-plugin-pygments/) - Adds [Pygments](http://pygments.org/) syntax highlighting to code snippets * [raw](https://github.com/docpad/docpad-plugin-raw) - Copies all files in the `/raw` directory to `/out` without going through DocPad's generation process. Useful for files that cause out of memory/speed issues when placed in `/static` directory. * [copy](https://github.com/almero-digital-marketing/docpad-plugin-copy) - Alternative to raw pluging with performace optimizations. Copies all files in the `/raw` directory to `/out` without going through DocPad's generation process. Useful for files that cause out of memory/speed issues when placed in `/static` directory. * [react](https://github.com/chrishale/docpad-plugin-react) - Renders markup for [React](http://facebook.github.io/react/) Components * [redirector](https://github.com/nfriedly/docpad-plugin-redirector) - Creats redirects (301 or meta-refresh) via configuration. * [related](https://github.com/docpad/docpad-plugin-related/) - Scans your documents `tags: 'tag1', 'tag2'` metadata to produce a listing of related documents * [rss](https://github.com/hurrymaplelad/docpad-plugin-rss) - Generates an RSS feed for a configurable collection * [scheduling](https://github.com/miletbaker/docpad-plugin-scheduling) - Schedules content so that it is not rendered out before the `date` specified in the content's meta-data. * [schema](https://www.npmjs.com/package/docpad-plugin-schema) - Adds support for JSON schema in DocPad collections * [services](https://github.com/docpad/docpad-plugin-services/) - Adds support for many 3rd party services to DocPad * [shortcodes](https://github.com/field/docpad-plugin-shortcodes) - Adds various Wordpress style shortcodes (e.g., `[video id="123"]`) to simplify template writing. * [sitemap](https://github.com/benjamind/docpad-plugin-sitemap) - Generates a `sitemap.xml` file for your site from the `html` documents collection * [tableofcontents](https://github.com/takitapart/docpad-plugin-tableofcontents) - Automatically generate table of contents * [text](https://github.com/docpad/docpad-plugin-text/) - Render `templateData` properties without needing template engine, useful for abstraction in configuration files * [thumbnails](https://github.com/rantecki/docpad-plugin-thumbnails) - Manages thumbnail generation of your image files * [imagin](https://github.com/almero-digital-marketing/docpad-plugin-imagin) - Alternative to thumbails plugin with support for `raw` and `copy` plugins for performance optimization. Manages thumbnail generation of your image files. * [tinylivereload](https://github.com/andruhon/docpad-plugin-tinylivereload) - A LiveReload plugin that doesn't alter your HTML. Works with the Chrome/Firefox LiveReload extensions. * [uglify](https://github.com/docpad/docpad-plugin-uglify) - Compress and minify JavaScript files with the `uglify: true` meta data * [umd](https://github.com/docpad/docpad-plugin-umd/) - Wrap specified JavaScript documents in the Universal Module Definition (UMD) allowing them to run in AMD, Require.js, CommonJS/Node.js and Vanilla environments automatically * [sanitizer](https://github.com/kennyki/docpad-plugin-sanitizer) - A helper for HTML string sanitization based on Google Caja ### Deployers <a href="#deployers" id="deployers"></a> These are plugins that make [deploying](https://docpad.org/docs/deploy) to particular services even easier: * [ghpages](https://github.com/docpad/docpad-plugin-ghpages) - Deploy to [GitHub Pages](http://pages.github.com/) as easy as `docpad deploy-ghpages` * [sunny](https://github.com/bobobo1618/docpad-plugin-sunny) - Uploads site to cloud (AWS, Google Storage) after generation ### Admin Interfaces <a href="#admin-interfaces" id="admin-interfaces"></a> {% hint style="danger" %} DocPad Admin Interfaces were [deprecated in DocPad v6.81](https://github.com/docpad/docpad/blob/master/HISTORY.md#v6810-2018-august-21) {% endhint %} [DocPad's plan from the very beginning has been to be interface agnostic.](https://github.com/bevry/docpad/issues/123) This means that we will be able to utilise existing interfaces, customer interfaces, and decoupled interfaces. Allowing us to always utilise the best experiences for everyone involved. #### Existing Interfaces <a href="#existing-interfaces" id="existing-interfaces"></a> DocPad's plugin/extension infrastructure supports existing coupled interfaces by importing their data directly into the DocPad Database. So if you love using Tumblr, WordPress, Medium, MongoDB, or GitHub repos for your content, you don't have to give them up. Just install the importer plugin for them, and DocPad will import the data from that service into the DocPad database for rendering. * [downloader](https://github.com/docpad/docpad-plugin-downloader/) - Download (and optionally extract) files into your project, used in the [Bootstrap Skeleton](https://github.com/docpad/twitter-bootstrap.docpad) to pull in [Bootstrap](http://getbootstrap.com/) * [repocloner](https://github.com/docpad/docpad-plugin-repocloner/) - Clone repos into your project, awesome for [creating wikis](https://gist.github.com/balupton/5519403) * [tumblr](https://github.com/docpad/docpad-plugin-tumblr/) - Imports Tumblr data directly into your DocPad Database, used in the [Syte Skeleton](https://github.com/docpad/syte.docpad) to pull in Tumblr data * [mongodb](https://github.com/nfriedly/docpad-plugin-mongodb) - Imports collections from MongoDB. * [cloudant](https://github.com/nfriedly/docpad-plugin-cloudant) - Imports collections from Cloudant (CouchDB) #### Custom Interfaces <a href="#custom-interfaces" id="custom-interfaces"></a> DocPad's plugin/extension infrastructure supports custom Admin Interfaces tightly coupled to the DocPad experience. So far we have the following extensions that add Admin Interfaces to DocPad: * [DocPad Collections Editor](https://github.com/cauld/docpad-collections-editor) - A simple WYSIWYG editor for DocPad Collections * [MiniCMS](https://npmjs.org/package/docpad-plugin-minicms) - Adds an admin interface to DocPad * [CMS Docpad](https://github.com/Reaktivate/docpad-cms) - Lightweight CMS UI with WYSIWYG editor for pages and parts #### Decoupled Interfaces <a href="#decoupled-interfaces" id="decoupled-interfaces"></a> DocPad's plugin/extension infrastructure supports existing decoupled interfaces by providing plugin/extension adapters to the interface allowing the interface to interact directly with the DocPad Database, or theoretically any backend providing an interface was made for it. So far we have the following extensions that add Decoupled Interfaces to DocPad: * [Use Prose with DocPad to create a Wiki](https://gist.github.com/balupton/5519403) - Tutorial on how to use [Prose.io](http://prose.io/#about) as an Admin Interface for DocPad * [WebWrite's InlineGUI](https://github.com/docpad/docpad-plugin-inlinegui) (not yet ready) - Edit your content from any backend with this inline editing interface * [Edit & Deploy with GitHub.com & GHpages Plugin](https://github.com/Sun-Star-IT/sunstarit.docpad/wiki/Edit-&-Deploy-with-GitHub.com-&-GHpages-Plugin) - Wiki on how to use GitHub.com to edit your DocPad website and then DocPad's `ghpages` plugin to deploy to GitHub Pages. ### Guides <a href="#guides" id="guides"></a> These are miscellaneous things that you can do with DocPad: * [Localising and formatting dates](https://gist.github.com/4166882) * [Automatically set custom meta data for collections](https://gist.github.com/4166806) * [Absolute URL Helper](https://gist.github.com/3939146) * [Benchmarking DocPad](https://gist.github.com/3906050) * [Sitemap Generation](https://gist.github.com/3898935) * [Concatenate your scripts with Browserify](https://gist.github.com/4398093) * [Minify your assets with Grunt](https://gist.github.com/3898915) * [Minify your assets automatically post-deployment with Cloudflare](http://blog.cloudflare.com/an-all-new-and-improved-autominify) * [Custom Routing](https://gist.github.com/3695936) * [Paging Solutions](https://gist.github.com/3695876) * [Responsive Layouts in Stylus](https://gist.github.com/1549029) * [Thoughts on a DocPad GUI](https://gist.github.com/2906284) * [Getting Ruby, SASS and DocPad working on Heroku](https://gist.github.com/4342818) * [Respond with JSON when asked to](https://github.com/lzrski/docpad-plugin-json) * [Require authentication to view certain documents](http://stackoverflow.com/q/14327676/130638) * [Use DocPad and GitHub as a Wiki](https://gist.github.com/balupton/5519403) ### Create Your Own! <a href="#create-your-own" id="create-your-own"></a> It's easy to write plugin for DocPad. [Get started now on our Write a Plugin Page!](/extend/plugin-write)[<br>](https://docpad.org/docs/participate) # Showcase A curated listing of DocPad projects and other resources. ### Projects Complete listings of DocPad projects can be found at: * [All GitHub projects that have the `docpad-project` topic](https://docpad.bevry.me/projects) ### News <a href="#news" id="news"></a> Official updates from the DocPad team: * [DocPad's Twitter](https://twitter.com/docpad) * [Bevry's Blog](https://blog.bevry.me/) ### Trainings <a href="#trainings" id="trainings"></a> Curated trainings covering DocPad. Oldest first. * [DocPad Workshop at HasGeek 1/2](https://www.youtube.com/watch?v=Zu1uhI0uT2o) - March 2013 * [DocPad Workshop at HasGeek 2/2](https://www.youtube.com/watch?v=-LxKYZDeSsc) - March 2013 * [PluralSight: Build a Better Blog with a Static Site Generator](https://www.pluralsight.com/courses/static-site-generator-build-better-blog) - [Intro Video](https://www.youtube.com/watch?v=gHz9ZyxwcGQ) - March 2016 ### Videos <a href="#videos" id="videos"></a> Curated videos about DocPad. Oldest first. * [Rapid Web Development with DocPad](https://www.youtube.com/watch?v=hvQCXDWh7Wg) - December 2012 * [Why DocPad Importers are HUGE!](https://www.youtube.com/watch?v=gEHXiZ4Wj4I) - July 2013 * [DocPad's Ecosystem](https://www.youtube.com/watch?v=5PxNY9w7Cj0) - September 2013 * [DocPad at Toronto Node.js Meetup](https://www.youtube.com/watch?v=i6dp_yqVCT0) - July 2013 ### Posts <a href="#posts" id="posts"></a> Curated community updates about DocPad. Oldest first. * [DogFeet on DocPad](http://dogfeet.github.com/articles/2011/docpad.html) - Korean: Covers what is DocPad, getting started with DocPad, and customising DocPad * [Dropbox auf dem eigenen Server](http://maxhaesslein.de/blog/1329055694) - German: Covers installing DropBox on both your local machine and your server's machine to easily sync your DocPad website * [HTML UI on DocPad](http://htmlui.com/blog/2011-08-01-site-templates-with-static-html-nodejs.html) - Extensive writeup on their thoughts of docpad and how they are using it * [Rebuilding JavaScriptQuiz.com with Node.js](http://www.aaron-powell.com/javascript/rebuilding-javascript-quiz-in-nodejs) - Covers their experience moving from Posterous to DocPad * [JekyllのNode版であるDocpadを使ってみる](http://tomohisaoda.com/posts/2012/using_docpad.html) - Japanese: Covers getting started with DocPad and a comparison with other static site generators * [Shop Talk Show Podcast](http://shoptalkshow.com/episodes/010-with-doug-neiner/) - A live web design and development podcast chat about the benefits of DocPad and [Doug Neiner's](http://code.dougneiner.com/) workflow (4 minutes in) * [DocPad Talk @ Paris.js](http://djebbz.github.com/docpad-paris-js/) - Presentation of DocPad at Paris.js, May 30th 2012 * [Rapid Web Development with DocPad](https://vimeo.com/53755097) - DocPad founder Benjamin Lupton gives an overview of DocPad and showcases what building a site is like in it * [Create professional websites with DocPad](http://emmet.io/blog/docpad/) - DocPad was an ideal solution for [Emmet documentation website](http://docs.emmet.io/) because it not only provides a simplified development process, but allows me to reduce my hosting costs greatly * [Why DocPad](http://takitapart.com/posts/why-docpad/) - Why I've built takitapart using a static site generator, and why DocPad won me over * [Organising DocPad](http://takitapart.com/posts/organizing-docpad/) - Setting up the basic taxonomy of [takitapart.](http://takitapart.com/) * [WordPress → Aegea → DocPad](http://blog.sapegin.me/all/docpad) - It was much simpler than I thought and I like the result very much * [Jekyll/Octopress to DocPad](http://blog.scriptybooks.com/from-jekyll-octopress-to-docpad/) - DocPad turned out to be the best platform for authoring interactive online technical books * [Static Site Generation with Node.js and CoffeeScript](http://www.coffeescriptlove.com/2013/05/static-site-generation-with-nodejs-and.html) - DocPad embraces CoffeeScript in a big way * [Converting to Docpad](http://fulljamesnet.herokuapp.com/articles/converting-to-docpad) - Web development worked perfectly * [How to contribute to the Topcoat blog](http://vimeo.com/68060525) - Walks you through Adobe's workflow of using DocPad for the [Topcoat website](http://topcoat.io/) and deploying to a GitHub Organisation Page * [WordPress out, DocPad in](http://joefleming.net/posts/wordpress-out-docpad-in/) - Docpad looked super flexible for generating static sites, but it also allowed you to add dynamic pages to the mix. I couldn't be happier! * [Multilingual blog on DocPad](http://blog.sapegin.me/all/multilingual-docpad) - How to make a multilingual blog with a single DocPad installation * [blogger-docpad](https://github.com/dorajistyle/blogger-docpad) - Import Google Blooger articles by label and generate Docpad static blog. It's good example how to handle large number of files with docpad. * [YTechie](http://www.ytechie.com/2013/11/blogging-awesomeness-with-a-static-generator-and-markdown/) - Blogging Awesomeness with a Static Generator and Markdown ### Websites <a href="#websites" id="websites"></a> Curated websites built with DocPad. Alphabetically sorted. * [Acherno Interior Design](http://acherno.com/) - Corporate web site of the biggest interior design studio in Bulgaria * [AlloyUI](http://alloyui.com/) - [source](https://github.com/liferay/alloyui.com) - AlloyUI is a UI framework built on top of YUI3 that provides a simple API for building high scalable applications * [Andrew Goodricke: Javascript Developer](http://andrewgoodricke.com/) - UK based Freelance JavaScript Web Application Developer with blog. * [Artem Sapegin](http://blog.sapegin.me/) - [source](https://github.com/sapegin/blog.sapegin.me) - Blog of Russian front-end developer: JavaScript, Stylus, Grunt.js, etc. * [Bevry](http://bevry.me/) - Creators of DocPad / Sydney based Node.js, JavaScript and HTML5 company focused on empowering developers. * [Black Market](http://blackmarket.bg/) - Bulgarian fashion company * [CoApp](http://coapp.org/) - [source](https://github.com/coapp/coapp.org) - CoApp is an open-source package management system for Windows * [Cumulocity](https://cumulocity.com/) - Internet of Things platform * [DataTables Taglib](http://tduchateau.github.com/DataTables-taglib/) - [source](https://github.com/tduchateau/DataTables-taglib/tree/gh-pages) - Website of DataTables-taglib, a JSP taglib that allows to quickly create [DataTables](http://datatables.net/) in Java/JEE based web application * [DeLingua](http://www.delingua.si/) - Slovenian translation company * [DogFeet](http://dogfeet.github.com/) - [source](https://github.com/dogfeet/dogfeet.docpad) - Korean: A development blog * [Dorajistyle STATIC](http://dorajistyle.net/) - Docpad generated Blog from Google Blogger articles. * [Doug Neiner's Code Website](http://code.dougneiner.com/) - [source](https://github.com/dcneiner/dougneiner.docpad) - Husband to one, father to three, jQuery Team Member, Senior Designer at [appendTo](http://appendto.com/) * [Emmet.io's Website](http://emmet.io/) - [source](https://github.com/emmetio/emmet-docs/) - Emmet (previously known as Zen Coding) is a web-developer’s toolkit that can greatly improve your HTML & CSS workflow * [Ferrari!=Ferrari](http://ferrari.github.io/) - Chinese: A development blog * [FizzVR](http://fizzvr.github.io/) - [source](https://github.com/fizzvr/vr-web) - Desarrollador web Backend Quito Ecuador * [Florian's Blog](http://blog.boulay.eu/) - [source](https://github.com/fboulay/website) - French: Technical blog on Java and technologies around the JVM * [Game-Icons](http://game-icons.net/) - Heaps of free SVG icons welcome to my online portfolio * [GreyCampus](http://www.greycampus.com/css-training-instructor-led) -The course offers complete information on Cascading Style Sheets (CSS) and teaches you how to control the look and feel of your HTML documents. This certification course also helps you in understanding the usage of fonts, colors, leading, and many other aspects. * [HTML UI](http://htmlui.com/index.html) - Website all about frontend development * [Imaginatr](http://www.imaginatr.com/) - Imaginatr is a creative independent studio focused on the development of mobile applications and innovative software * [Jose Quesada](http://josequesada.com/) - [source](https://github.com/quesada/josequesada.docpad) - Homepage of Jose Quesada, a specialist with e-commerce database marketing * [Kyle Pool](http://kylpo.com/) - [source](https://github.com/kylpo/kylpo.com) - I'm in practice-mode: working hard for a successful life that improves the world. * [Leigh Howells](http://leighhowells.com/) - Home planet, blog and portfolio of Designer, tunesmith and UX Consultant, Cambridge, UK. With added aliens. * [The Mason Jar](http://www.the-mason-jar.com/) - [source](https://github.com/the-mason-jar/www-the-mason-jar) - Hipster cocktails with a back-end powered by GitHub and DocPad. * [MeltMedia](http://meltmedia.com/) - An enterprise level web application development firm and interactive design agency based in Tempe, Arizona * [MS Dev Show](http://msdevshow.com/) - The MS Dev Show is the podcast for Microsoft developers covering news and topics such as Azure (cloud), Windows, and cross-platform development using MS tools. * [Open Device Lab Hamburg](http://hamburg.opendevicelab.de/) - Open Device Lab Hamburg. Come and test your Websites on a wide range of devices for free! * [pimatic](http://www.pimatic.org/) - smart home automation for the raspberry pi * [Remy Bach](http://remy.bach.me.uk/) - I'm a Christian, husband and father, front-end dev, gamer, and all around tech nerd! * [Rob Rawkes](http://rawkes.com/) - Rawkes is the home of Rob Hawkes, part-time Rawket Scientist and full-time geek. Join him as he explores the outer-reaches of programming, digital media, games, and everything in-between. * [ShareLaTeX.com Blog](https://www.sharelatex.com/blog/) - Used to generate static pages for the blog * [Surrey Vascular Surgeon](http://www.surreyvascularsurgeon.com/) - Used to create a wesbite to explain vascular surgical services provided by me. Wanted a static website with fast load times. * [takitapart.](http://takitapart.com/) - akitapart. - pronounced "take-it-apart" - is the blog of Bob VanderClay, web application developer, founding partner at high90, and all around nerd * [The Open Document Format](http://www.opendocumentformat.org/) - The official website of the OpenOffice ODF file format * [Tomohisa Oda](http://tomohisaoda.com/) - Japanese: Web engineer and designer from Japan * [Topcoat.io](http://topcoat.io/) - CSS for clean and fast web apps by Adobe * [The Open Document Format's Plugfest](http://www.odfplugfest.org/) - The ODF plugfests are an ongoing series of vendor-neutral events, bringing together implementers and stakeholders of the standard * [Vicktor Ilieff](http://www.viktorilieff.com/) - Viktor Ilieff is an artist, conductor, composer and visionary. His art rests on the principle that the aesthetics of the means of expression should align with the times we live in. * [v1rtual](http://v1rtual.net/) - English & German: Blog about hacking, electronics, turtels and stuff * [Notes From Heck](http://adityamukho.com/) - Personal website and blog of Aditya Mukhopadhyay, built on the bootstrap skeleton. * [YTechie](http://www.ytechie.com/) - Blog for Jason Young, Azure Developer and Evangelist [<br>](https://docpad.org/docs/roadmap) # Roadmap This page serves as a roadmap what DocPad has done and plans to do. [You can find out what we have planned over at our GitHub Issues.](https://github.com/docpad/docpad/issues) [Want to help? Check out our Contribute Guide.](/community/contribute) ### Done <a href="#done" id="done"></a> #### Version 6 <a href="#version-6" id="version-6"></a> * v6.60 * Added caching HTTP headers * v6.59 * [Fix Watchr once and for all](https://github.com/bevry/watchr/issues/33) * v6.58 * Dynamic documents are rendered through the generate action * v6.56 * Database caching disabled by default * v6.55 * Database caching aka [Importer Speed Optimisations](https://github.com/bevry/docpad/issues/590) * v6.54 * Abstracted out notifications into plugin * i18n support without native binary * v6.53 * Locales can now be merged together * v6.51 * Run the local DocPad installation if it exists * v6.49 * Cleanup on destroy * v6.48 * Version conflict warning * v6.47 * Inline elements in styles block * v6.46 * [Importer support](https://github.com/bevry/watchr/issues/500) * v6.45 * Added `docpad update` command * v6.44 * Virtual document support * v6.43 * Added `docpad install` command * v6.41 * Debugging and tracing improvements * v6.38 * Init empty directories * v6.35 * Plugin priorities * v6.32 * Streams based logging * v6.31 * Progress bar for generation * v6.30 * Abstracting out the core begins * v6.26 * Node 0.10 support * v6.25 * Persistant database * v6.24 * Plugins can now extend the CLI * v6.23 * Foreign encoding support * v6.13 * Statistics * v6.8 * `.env` file support * v6.7 * [Express.js](http://expressjs.com/) v3 support * v6.6 * Added `docpad-debug` executable * v6.4 * Custom error pages * v6.3 * Multiple environment support * v6.2 * Environment specific configuration * Better Node.js deployments * Better extendability * v6.1 * [Element based renderers](https://github.com/bevry/docpad/issues/194) * v6.0 * Added differential rendering * Allow configuration files to hook into events * Streamlined and cleaned * Extensible CLI #### Version 5 <a href="#version-5" id="version-5"></a> * v5.2 * Everything is now parsed into the in-memory database * Added `docpad.cson` configuration * Added custom collections via configuration support * v5.1 * Added support for binary files * v5.0 * Plugins are now handled via NPM * Uses Backbone for Models and Collections #### Version 4 <a href="#version-4" id="version-4"></a> * v4.1 * Added skeleton exchange * v4.0 * Added support for partials #### Version 3 <a href="#version-3" id="version-3"></a> * v3.2 * You can now select which skeleton on creation of a new project * Unit Tests * Modular API for rendering single files * Modular API for rendering single content blocks * Hidden files are now ignored in watchr * v3.1 * Added an interactive CLI * v3.0 * New event system, which supports blocking and queuing of events #### Version 2 <a href="#version-2" id="version-2"></a> Version 2 focused on improving the possibilities of the plugin infrastructure as well as adding support for windows and cloud based services. * v2.3 * Cloud Support * v2.2 * Windows Support * v2.1 * Dynamic Documents * These are rendered per request, and have access to the Express.js request object * They enable things like form handling, search, real-time updating data, etc. * v2.0 * Plugin's have their own `package.json` * This specifies the plugin's dependencies * When the plugin is used, DocPad will do a `cd $pluginDir; npm install` * Plugins and DocPad configurable through project's `package.json` * Plugins and DocPad configurable through project's `docpad.coffee` * Front-End Administration Plugin * Adds in some client-side JavaScript * Utilises contentEditable with semantic properties to update * REST Plugin * Support read and write of files * Requires some sort of authentication method... to be decided #### Version 1 <a href="#version-1" id="version-1"></a> Version 1 focused on improving the scalability, stability, and ease-of-use of DocPad. Bringing it to a vastly superior alternative to other static site generators. #### Version 0 <a href="#version-0" id="version-0"></a> Version 0 focused on fixing the content creation and website development pain.