Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
DocPad plugin that fetches any associated files for our particular document
CoffeeScript HTML
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
src
test Add tests and documentation for useRelative
.editorconfig
.gitignore
.npmignore
.travis.yml
CONTRIBUTING.md updated base files
Cakefile
HISTORY.md Fix documentation to reference associatedFilePath correctly - fixes #3
LICENSE.md
README.md
coffeelint.json
package.json

README.md

Associated Files Plugin for DocPad

Build Status NPM version NPM downloads Dependency Status Dev Dependency Status
Gratipay donate button Flattr donate button PayPayl donate button BitCoin donate button Wishlist browse button

This plugin streamlines finding associated files for a particular document in DocPad, which is useful for:

  • getting images for a gallery
  • getting downloads for an article
  • etc. etc.

Install

docpad install associatedfiles

Usage

The way it works is by looking into src/files/associated-files/#{document.associatedFilesPath or document.basename} for files. Where associatedFilesPath is set in your document's meta data, and if it doesn't exist it will use the document's basename (e.g. the basename of my-holiday-2012.html.eco is my-holiday-2012). Any files inside that path will be associated to your document, and retrieveable by @getDocument().getAssociatedFiles()

Lets see how this works, we have the document src/documents/my-holiday-2012.html.eco:

---
title: My Holiday in 2012
---

<h2>Here are some great photos from our trip</h2>

<% for file in @getDocument().getAssociatedFiles().toJSON(): %>
<p>
    <h3><%= file.title or file.name %></h3>
    <img src="<%= file.url %>" title="<%= file.title or file.name %>" />
</p>
<% end %>

Then we will stick a few images inside our path: src/files/associated-files/my-holiday-2012. And we'll end up with the rendered result:

<h2>Here are some great photos from our trip</h2>

<p>
    <h3>sweet-sweet-beach.jpg</h3>
    <img src="/associated-files/my-holiday-2012/sweet-sweet-beach.jpg" title="sweet-sweet-beach.jpg" />
</p>

<p>
    <h3>sweet-sweet-icecream.jpg</h3>
    <img src="/associated-files/my-holiday-2012/sweet-sweet-icecream.jpg" title="sweet-sweet-icecream.jpg" />
</p>

Configure

Defaults

The default configuration for this plugin is the equivalant of adding the following options to your DocPad configuration file:

plugins:
    associatedfiles:
        # The paths for the associated files.
        associatedFilesPath: 'associated-files'

        # Whether to use relative base paths for the document. This would
        # use associated-files/subfolder/myarticle/image.jpg instead of
        # associated-files/myarticle/image.jpg.
        useRelativeBase: false

Template Configuration

It is possible to override the default configuration on a per-template basis:

---
associatedFilesRelative: true
associatedFilesPath: './myfolder'
---

<% for file in @getDocument().getAssociatedFiles().toJSON(): %>
<p>
    <h3><%= file.title or file.name %></h3>
    <img src="<%= file.url %>" title="<%= file.title or file.name %>" />
</p>
<% end %>

History

Discover the change history by heading on over to the HISTORY.md file.

Contribute

Discover how you can contribute by heading on over to the CONTRIBUTING.md file.

Backers

Maintainers

These amazing people are maintaining this project:

Sponsors

No sponsors yet! Will you be the first?

Gratipay donate button Flattr donate button PayPayl donate button BitCoin donate button Wishlist browse button

Contributors

These amazing people have contributed code to this project:

Become a contributor!

License

Unless stated otherwise all works are:

and licensed under:

Something went wrong with that request. Please try again.