reusable templates as a Node modules

[dylang]

It should be easy to put my templates I want to share across projects into a separate Node module.

All assembly-specific templates would be in something called templates-assembly, my templates might be in a module called templates-dylang.

The files in /templates should be in separate modules as well. This way I can use them without worrying about the content changing next time I upgrade grunt-readme.

I think the way to use the templates would be configured would be something like this:

templates: [
  'templates-grunt-plugin',
  'templates-badges',
  'templates-licenses',
  'templates-assembly',
  '/templates'
]

Using _.include(fileName) would use the first match, starting with /templates.

[jonschlinkert]

yeah this is definitely something that needs to be here. I'll work on adding this

[jonschlinkert]

btw, there is already a mixin called _.resolve() that you can use to include templates from node_modules, https://github.com/assemble/grunt-readme/blob/master/tasks/lib/mixins.js#L34-L47, but it doesn't work as you described. and after reading through again I'm not sure I understand the last part. Where would the templates: [] array be, and how would that be used?

[dylang]

I looked at _.resolve() after I created this ticket. I looked to me like the node module's main must point to a single template, as opposed to the node module containing multiple template files.

Where would the templates: [] array be?

In the Gruntfile.js config block for readme.

and how would that be used?

templates: [
  'templates-grunt-plugin',
  'templates-badges',
  'templates-licenses',
  'templates-assembly',
  '/templates'
]

So using the example above, lets say templates-grunt-plugin includes 'getting-started.md', 'options.md', 'about-author.md'.

• getting-started.md is perfect for any of Assembly Grunt projects so we won't replace it.
• options.md needs to specific to the project, so we will add an options.md to the /templates directory. This means /templates/options.md will be used instead of the one in templates-grunt-plugin.
• about-author.md is going to be same for all Assembly projects so we'll put our Assembly-specific template in templates-assembly. If we need to make a different version of about-author.md for a specific project then we'll include it in that project in /templates/about-author.md.

In /templates/README.tmpl.md we'll have something like:

{%= _.include('getting-started.md') %}

{%= _.include('options.md') %}

{%= _.include('about-author.md') %}

Simplified for purpose of example, there would obviously be more sections.

If getting-started.md has badges, it would use the same logic. templates-badges might have our default set, but templates-assembly might have variations or additions, and same thing in /templates which would take precedence.

[jonschlinkert]

great, thanks for the additional clarification! this helps

[jonschlinkert]

@dylang, I think you will like how I handle this in Verb.

Also, just wanted to mention that there are a couple of syntax changes (I'm documenting these changes, some of it is already mentioned in the Verb docs), Verb uses {%= include('options') %}, without the _. or the file extension.