What are the differences between all those paths in DocPad's document metadata?

Question

What are the differences between all those paths in DocPad's document metadata?

Each document have a set of metadata with a lot of different kinds of paths and filenames, here is an example list:

fullPath: '/Users/kizu/Projects/docpad-test/src/documents/pages/page2_en/index.html.md',
relativePath: 'pages/page2_en/index.html.md',
basename: 'index',
outBasename: 'index',
filename: 'index.html.md',
fullDirPath: '/Users/kizu/Projects/docpad-test/src/documents/pages/page2_en',
outPath: '/Users/kizu/Projects/docpad-test/out/en/pages/page2/index.html',
outDirPath: '/Users/kizu/Projects/docpad-test/out/pages/page2_en',
outFilename: 'index.html',
relativeOutPath: 'en/pages/page2/index.html',
relativeDirPath: 'pages/page2_en',
relativeOutDirPath: 'en/pages/page2_en',
relativeBase: 'pages/page2_en/index',
relativeOutBase: 'pages/page2_en/index',
name: 'index.html',
slug: 'pages-page2-en-index',
url: '/en/pages/page2/index.html',
urls: [ '/en/pages/page2/index.html' ],

I know the purpose for only two of those metadatas:

1. outPath sets the output path in the file system, so by changing it on renderBefore event would change the output path and the filename.

2. url is the absolute url from the root of the site, it is mostly used for linking to other documents.

But what are the purposes for all other paths and names? Are there plugins that use them, or code features of DocPad that rely on these?

The context of the question is similar to the answers to this one: I want to rewrite the output paths and filenames of my documents, so I need to know what metadata I need to change. Right now I change only the outPath and url, but is it enought? Or maybe there is a way to change the output path using just one magic method, so it would change all those paths to the proper new ones automatically, so I won't need to bother about this at all?

Answer 1

I think most of these are paths relative to the Docpad.coffee files configuration for rootPath (where the docpad.coffee file is), outPath(where the generated website goes),srcPath (where the website source files are), documentsPath (where the files to be rendered are) and filesPath (website assets and the like that don't need to be rendered). See http://docpad.org/docs/config

Docpad uses stores the various paths so it doesn't need to recalculate those paths each time it needs to do something with the file - render it from here and output it there...

The good news is that this metadata is calculated depending on where the file is saved when Docpad loads it into its database (and then regenerates the website).

The other good news is that the documentsPath is an array - so you can have multiple locations to save documents to be rendered and output.

But I think the answer to your question is that you don't need to change the metadata - its dependant on where your file is saved. Does that make sense?

Edit

Just thought of a way to test this. Create two folders underneath the documents folder called "loc1" and "loc2". In "loc1" place an "index.html.eco" file with the following content.

---
layout: 'default'
title: 'Home'
---

<h3><%-@document.title%></h3>
<ul>
    <% for key, val of @document: %>
    <li>
        <span><%-key%> = <%-val%></span>
    </li>
    <% end %>
</ul>

This will print out all the properties of the current document - ie index.html.eco. Start up docpad and view the page. The relativePath property should be something like loc1\index.html.eco.

Now, whilst docpad is still running, copy this file to the loc2 folder. You should see docpad regenerate the website.

Now web browse to the "loc2" location and you should see a similar output, but with loc2 instead of loc1 in the output metadata.

Edit

What I've done on a similar idea is to hook in to the serverExtend event, like this:

   # Server Extend
    serverExtend: (opts) ->  
        safefs = require('safefs')
        server.post '/listentry', (req,res,next) ->
            safefs.writeFile outFile, content, (err) ->
                return next(err)  if err

The idea here is to write a file to a different location depending on what the post URL is. So, as a consequence of this the saved file will have the corresponding metadata. If we were to take the example of saving different language files, we could have logic here to save multiple files in different locations or file names according to each language.

Now, if you want to serve different documents according to some criteria, you might do this:

                server.get 'someurllogic', (req,res,next) ->
                    #do something with the url logic                    
                    document = docpad.getCollection('documents')
                        .findOne({relativeOutPath: resultOfUrlLogic+'index.html'});
                        docpad.serveDocument({
                            document: document,
                            req: req,
                            res: res,
                            next: next,
                            statusCode: 200
                    });

To take the language example, you might have some logic to determine the language to be served - user agent perhaps - and serve the appropriate document to match.

Another possibility is that you can add metadata to your document when it is saved that will help you select the appropriate document in your server.get handler. This could be in the same way that you include metadata in a markdown file like this:

---
layout: 'default'
title: 'My title'
tags: ['news','node']
mySelectionCriteria: 'selectionCriteria'
---

There's really no limit to the metadata you can add