Make includes directory configurable

[valtlai]

This implements the possibility of configuring the includes directory proposed in #111:

• Adds a new --includes CLI option.
• Adds site.options.includes and a includes option for eta, nunjucks and pug.
• Adds a options option for pug.
• Adds site.includes(), similar to site.src().
• Replaces the hard coded include paths with site.includes().

@oscarotero, what do you think? Do we need this?

We should also decide what should happen if the specified includes directory doesn’t start with _ (or .). Should we throw an error or just ignore the directory (like site.ignore(site.includes()))?

[oscarotero]

Nice approach. One thing that I have thought about was including the possibility to configure different includes. For example, it may be more practical for some users if the css files are in /_css instead _includes/css, and the same for layouts, etc. This requires to have this option at the plugin level, not site level. For instance:

site.use(postcss({ includes: "_css" });

In fact, it's something already implemented for postcss, but not other plugins like nunjucks, eta or pug.

I think this is a more flexible solution. The plugins can have the _includes folder by default (and maybe this folder can be configured in the site, using your changes here), but with the possibility to change them.

To me, the --includes argument in CLI is a bit excesive, I can't think of a use case for that.

About the directories that doesn't start with _ or ., good point.

• I think site.ignore(site.includes()) is an easy and clean solution.
• But, in the other hand, the user may not want to ignore this folder for any reason:
  • Because the includes files is in a subdirectory
  • Because she want to reuse a page as a template (crazy idea)
  • Because mixes pages and layouts in the same folder, and use _ to ignore the layouts. For example:

    pages/
      page-1.md
      page-2.njk
      _layout.njk
    

So, maybe the best approach is doing nothing? Just include in the documentation a text indicating that the includes folder/files should be ignored someway.

What do you think?

[valtlai]

I agree the --includes option is probably useless, so I removed it. I’m fine with doing nothing with include directories not starting with _ or ..

It’s good idea to have the includes option at the plugin level too. For example, should I

1. pass the full options object containing both options.includes and options.options to the NunjucksEngines’s constructor

   // plugins/nunjucks.js:17
   const nunjucksEngine = new NunjucksEngine(site, options);
   
   // engines/nunjucks.js:10
   const loader = new nunjucks.FileSystemLoader(options.includes);
   this.engine = new nunjucks.Environment(loader, options.options);

2. pass a new object containing only options.includes and options.options to the constructor

   // plugins/nunjucks.js:17
   const nunjucksEngine = new NunjucksEngine(site, { options.includes, options.options });
   
   // engines/nunjucks.js:10
   const loader = new nunjucks.FileSystemLoader(options.includes);
   this.engine = new nunjucks.Environment(loader, options.options);

3. or add a new argument for the includes directory to the constructor?

   // plugins/nunjucks.js:17
   const nunjucksEngine = new NunjucksEngine(site, options.options, options.includes);
   
   // engines/nunjucks.js:7
   constructor(site, options, includes) {
   // :10
   const loader = new nunjucks.FileSystemLoader(includes);

[oscarotero]

Probably, I'd create the nunjucks instance out of the NunjucksEngine constructor. I like the idea of having the engines as much light as possible, so they can be reused with a custom instance if you want (for example, creating your different nunjucks plugin but reusing the same engine).

This is something that I did with markdown engine: https://github.com/lumeland/lume/blob/master/engines/markdown.js (the markdown-it instance is created in the plugin file and passed to the engine in the constructor).

[valtlai]

Okay, I’ll try that later, but feel free to push commit(s) here if you like.

[valtlai]

Thanks for those commits!

Added a plugin-level includes option for the nunjucks and eta plugins, but not really for pug, because the include path is set in the engine instead of the plugin.

[oscarotero]

Nice! I just commited a change to configure the pug engine, including the basedir (includes) from the plugin.