Nanoc, Routes and File Extensions

So I’ve encountered my first major nuisance in using nanoc. In nanoc, the filenames of source files are treated rather unintuitively and it can be confusing why one can’t have multiple files with the same name but different extensions at first. I haven’t found a lot of information about this so I’ll put down a quick writup on this.

Nanoc treats each source file as a different atomic “item” (in nanoc speak.) Each item is identified by the path to that item from the source (“content”) root, plus the name of the item, minus any extension. So, a file in “content/posts/somesillypost.erb” would be identified by nanoc with “/posts/somesillypost/”. Notice that the extension “.erb” is dropped. Nanoc treats all file with the same name as part of the same item regardless of extension. This makes sense from nanoc’s perspective because an item can have multiple files associated with it (usually a source file with an “.html” or “.erb” extension and a metadatafile withe a “.yaml” extension.) The consequence of this is that if you have two files with the same name and different extensions, for example, “resume.html” and “resume.pdf,” then nanoc will throw an error because it sees the two as conflicting resources.

Working around this is simple, if unintuitive. You can’t have multiple source file with the same name and different extension, but you can have multiple output files with the same name and different extension. You just have to name your files something like “resume_html” and “resume_pdf” and create the correct routes in the Rules file to transform them:

route '/resume_html/' do
  "/resume.html"
end
route '/resume_pdf/' do
  "/resume.pdf"
end

In this example, the source files with names like “file_html” are converted to output file with names like “file.html”.

You can actually generalize this so that final underscores are always converted to “.”

route '*' do
  *filename, extension = item.identifier.split "_"
  filename.join("_") + "." + extension
end

So now any file named “/just_a_sample/html_file_html” will be output as “/just_a_sample/html_file.html”

The key points to take away here are that

nanoc treates its source, not as a collection of files, but as a collection of ‘items’ which each can consist of more than one file.
Items are identified by their paths, including filename sans extension, which nanoc uses for other things.
You can’t have multiple files of the same name but with different extensions because nanoc will conflate them, but you can have multiple output files with the same name and different extensions if you just use the correct routes in the Rules file.