Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Being able to modify file's output folder/filename #648

greduan opened this Issue Sep 18, 2013 · 26 comments


None yet
5 participants

greduan commented Sep 18, 2013

Would be nice to be able to have something like this:

      - file1.html.md
      - file2.html.md

And the first file has:

title: whatever
layout: post
date: 2013-08-18
output: /2013/08/whatever

post content or whatever, seriously.

And the output would be:

        - whatever.html
    - file2.html.md

See where I'm getting at? It would be kind of a pain to create the 2013/08 folders and imagine doing that for each month, maybe days if I wanted to. Not ideal.

Also this allows the user to order their files using stuff like 01-filename.html.md etc.

So yeah, would be nice to see this implemented. :)

Want to back this issue? Place a bounty on it! We accept bounties via Bountysource.


chase commented Sep 18, 2013

You could always implement a plugin to do this. I'm sure it would be greatly appreciated.


greduan commented Sep 19, 2013

I could. I'll look into it. This looks like something that should be in core though. Still, I'll look into it.


chase commented Sep 19, 2013

@greduan, we are progressively moving away from the monolithic core approach and heading toward a more modular way of handling things.
Also, implementing it as a plugin would also make it easier to adapt once we do a major rewrite of DocPad.


greduan commented Sep 19, 2013

Ah gotcha. Yeah the way things are right now, seems like it should be in core, for the future though... Added to my todo list. :)

Plus five for this. I always thought it might be in the core somewhere but I couldn't find it. The document module contains many seemingly overlapping values... url, path, relativePath, etc. (I don't remember the exact names right now). Maybe looking at the cleanurls plug-in to get an idea how to do this.


greduan commented Sep 19, 2013

Just remember all that stuff to modify the URL requires the server to be running Node.js, that's why you need to do it the folder way. Learned this the hard way.

And initially I did manually make the folders for the date, but I can't seem to get DocPad to track posts under those folders (https://github.com/Greduan/eduantech.docpad/blob/master/docpad.coffee#L49), can't get it to track subfolders, only the folder I'm specifically pointing to. So that didn't work either.

So for now I didn't go with dates in the URL, will in the future once this is fixed though. ;)


greduan commented Sep 19, 2013

Oh and for a quick explanation between stuff like relativeOutDirPath and relativeDirPath basically means the path of the folder after and before render, respectively. That's what I understand at least from the descriptions. Took me a while to figure out as well.

@greduan I'm not sure what you mean by "stuff to modify the URL". The clean urls plug-in renders (for example) /my-post.html.md to /my-post/index.html and also creates a /my-post.html file that redirect to /my-post/. No node server is needed.

Also, for what it's worth, I created a command line tool frontman to handle yaml front matter files. Using some properly formatted templates (yet to be documented) I can create a draft post in a draft folder that is only rendered in development mode then use another template to change the publication date, tag it as published, and move it to the /archives/year/month/day folder when the post is done. It works well, imo, but a plugin to alter a documents relativeOutDirPath during render, based on metadata, would really help docpad in the blogging realm (where jekkyl is king).


greduan commented Sep 19, 2013

Oh I was not aware. I thought it worked similarly to the... Oh now I can't find it... I remember there was a plugin that required it being a dynamic environment... That's a cool tool. :)

Well I guess I'll use those plugins as a reference for what I do. Ideas on name for the plugin?

Here is a gist showing how to Draft and publish a blog post in docpad using frontman.

I don't want to hijack this thread anymore... if you try and have issues please contact me.


greduan commented Sep 20, 2013

Don't worry about it. :) Thanks for the Gist. All this stuff you've mentioned will make it easier for me to make the plugin when I find time. ;)

Please make it configurable. The default could be to move src\_posts to src\year\month\day or whatever but the ability to set any number of source directories and an output rewrite function would be a great tool.


greduan commented Sep 20, 2013

The idea is to make it so that it's moved according to the file's location. If it's location is /src/render/posts/file.html.md then for it to end up in /src/render/posts/2013/12/12/file.html.md it would be:

output: 2013/12/12/*

I plan on making * stand for the file's name, so that you don't have to type it out if you don't want to change the name. Open for suggestions.

Of course a ./ can be added for the same effect, so it's like this:

output: ./2013/12/12/*

If the setting is /* it would mean the root, so it would appear on the output of /src/render/file.html.md. See what I mean?

And of course if you want you can go up folders (..) etc.

I plan on making it work as similar as possible to how the *nix command line works.

So the name is open for suggestions as well, and of course the argument that would be put on the head. Anything you think should be different feel free to express as well so that I can take it into account. :)

Yes, specifing an out directory in the metadata is nice and simple (and easily modified using something like... frontman :). What I was thinking was more like the apache url-rewrite patterns that can be specified in the coffee config using regular expressions. For example:

    /^\/_posts\/(.*)/:   "/blog/archive/$1"
    "^/([uge])/([^/]+)$":  "/$1/$2/"

etc. Plus some way to use the document metadata. Maybe:

    "^/_posts/(.*)":   "/blog/archive/#{output}/$1"

I would call this docpad-plugin-url-rewrite. Perhaps needs to play nicely with docpad-plugin-geturl.


greduan commented Sep 20, 2013

I see, I'll look into it. I'm not very familiar with Apache and/or it's url-rewrite patterns, but I'll consider it.

I want to keep it as simple as possible so that you don't really need to learn something new to use it but rather use what you already know. Perhaps I can make a simple version and then add the advanced stuff later on.

In any case it'll be in consideration, including the name, thanks for that. :)

Thinking about this more... it's really just a collection of str.replace(searchvalue, newvalue) that are applied to each url before writing. The collection can be specified in the docpad config or in the metadata of the file being generated. The default url-rewrite rule can be exactly as simple as you said. Just need to make sure this happens early enough that the collections reference the new url. docpad-plugin-geturl is set to get a documents url from document model so it should play nice. @getUrl('') should return the current documents url after rewrite.


balupton commented Sep 21, 2013

You should be able to accomplish this by setting the outPath accordingly:

outPath: 'blah/blah/blah.html'

or adding a url to the urls field:

urls: ['blah/blah/blah.html]

combine that with an auto setter like https://gist.github.com/4166806 to make this happen automatically

I tried this before but failed. I just tried again. with no better luck.

If I create a new file at src/documents/drafts/new.html.md with the following front matter:

layout: post
title: 'new'
post_name: 'new'
status: draft
  - post

I get a out/drafts/new.html file as expected. If I add the following metadata:

outPath: 'archives/test/test.html'

It doesn't create the archives/test/ directory or the test.html file. In fact it stalls at Currently on writeFiles at 63/64. I've tried various forms of outPath (windows backslash, relative, absolute, etc) without any luck. All with the same results. I've also tried creating the archives/test/ with no change in results. Always stalls at 63/64.


balupton commented Sep 22, 2013

That's strange... is the site you're working on public? If so, could you make a branch available to me with this so I can debug?


greduan commented Sep 22, 2013

I will try this later today, glad to know it's already implemented, makes my life a whole lot easier. I created a repo for the plugin.

Feel free to implement this plugin yourself in your own repo if I don't get to it soon enough, now that I know of outPath I'm not as excited on solving this, since it's already solved apparently.

I guess the first question is do we need to explicitly specify the out path?

outPath: 'out/archives/test/test.html'

If I do this docpad generates the correct html file but the cleanurls plugin creates an out/out path. If I don't include out in the path docpad hangs on writeFiles... like I indicated above.

Here is a test repository. There are three test files under src/posts. As is it fails on test3.



greduan commented Sep 23, 2013

I can confirm if I don't specify out at the beginning of the argument it stalls. However if I do specify it it includes out/ in the URL.


greduan commented Sep 23, 2013

After some further testing it turns out it works fine, until you add a folder (i.e. a slash /). Or of course when you add out/ to the value but then out/ is also part of the URL.

@balupton Any thoughts on this? Is it a bug in docpad or clean-urls?


greduan commented Oct 5, 2013

@Hypercubed From my tests it seems to be a bug in DocPad...

Has there been any progress on this? It would be great if we could get custom outPath settings per collection since the way I like to organize stuff is often not the same way I want to expose it on the web.

For example I keep all my pages (well markdown documents that will eventually become pages) that I want accessible at the root of the domain domain in their own folder _pages I would like these markdown documents to be processed and outputted directly to the outPath. I tried setting the outPath per collection but adding this to my docpad.coffee

    pages: ->
     @getCollection("html").findAllLive({relativeDirPath: 'pages'}).on "add", (model) ->
        model.setMetaDefaults({layout: "default"})
        model.setMeta({outPath: 'dist' })    

Unfortunately this doesn't work as it outputs every page in the collection with the filename dist instead of dist/filename.html which is what I am looking for.

Is this a bug? Or am I doing it wrong (something that happens very often to me).


Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment