https://github.com/docpad/docpad-plugin-associatedfiles

DocPad plugin that fetches any associated files for our particular document
https://github.com/docpad/docpad-plugin-associatedfiles

docpad-plugin

Last synced: about 1 year ago
JSON representation

DocPad plugin that fetches any associated files for our particular document

Host: GitHub
URL: https://github.com/docpad/docpad-plugin-associatedfiles
Owner: docpad
License: other
Created: 2012-10-17T01:58:38.000Z (over 13 years ago)
Default Branch: master
Last Pushed: 2024-02-04T18:38:41.000Z (over 2 years ago)
Last Synced: 2025-05-07T03:15:01.905Z (about 1 year ago)
Topics: docpad-plugin
Language: JavaScript
Homepage:
Size: 216 KB
Stars: 7
Watchers: 13
Forks: 6
Open Issues: 7
Metadata Files:
- Readme: README.md
- Changelog: HISTORY.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md

Awesome Lists containing this project

README

# Associated Files Plugin for [DocPad](http://docpad.org)

This plugin streamlines finding associated files for a particular document in [DocPad](https://docpad.org), which is useful for:

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

## Install

```bash
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`:

```html
---
title: My Holiday in 2012
---

Here are some great photos from our trip

<% for file in @getDocument().getAssociatedFiles().toJSON(): %>

<%= file.title or file.name %>

<% 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:

```html

Here are some great photos from our trip

sweet-sweet-beach.jpg

sweet-sweet-icecream.jpg

```

## Configure

### Defaults

The default configuration for this plugin is the equivalant of adding the following options to your [DocPad configuration file](http://docpad.org/docs/config):

```coffee
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:

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

<% for file in @getDocument().getAssociatedFiles().toJSON(): %>