What template tags do I use?

[michaelkornblum]

I've been looking for a plugin like this one for some time now. But how would I render the archives in my template?

[flatiron32]

It would be nice to know how exactly this is to be used. It is not clear from the docs. I can see from the code there will be a map with year as the key and a list of files as the value, but I am not sure what to do with that.

[thevasya]

It adds an array with yearly data under archive key to Metalsmith metadata object, each array item is something like { year: '2014', data: [<all_posts_from_2014>] }.

So in your templates you iterate over the archive like this:

{% for posts_by_year in archive %}
    <h3>{{ posts_by_year.year }}</h3>
    <ul class="post-list">
    {% for post in posts_by_year.data %}
        <li>
            <time>{{ post.date }}</time>
            <span>{{ post.title }}</span>
        </li>
    {% endfor %}
    </ul>
{% endfor %}

[petermorlion]

Still took me some time to figure it out (not being a Metalsmith expert). So, for those using the markdown and layouts (with handlebars) approach as put forward in on the metalsmith homepage, you can do something like this:

Create a markdown page, like you would for your other pages/posts:

    ---
    title: Archive
    layout: archive.html
    ---

I have no content, because my archive will be just a list of blog posts, but you could add content, and then display that in your template.

Create the Handlebars template

    {{> precontent }}

    <h1>{{title}}</h1>

    {{#each archive}}
    <h2>{{ this.year }}</h2>
    <ul>
      {{#each data}}
      <li>{{this.title}}</li>
      {{/each}}
    </ul>
    {{/each}}

    {{> postcontent }}

Add archive to your main file (I'm using the js approach, not the JSON approach), for example:

require('./node_modules/harmonize')();

var Metalsmith = require('./node_modules/metalsmith'),
        layouts    = require('./node_modules/metalsmith-layouts'),
        markdown   = require('./node_modules/metalsmith-markdown'),
        archive    = require('./node_modules/metalsmith-archive');

Metalsmith(__dirname)
  .source('./src')
  .destination('./build')
  .use(markdown())
  .use(archive({
    collections: '.'
  }))
  .use(layouts({
    engine: 'handlebars',
    partials: 'partials'
  }))  
  .build(function(err) {
    if (err){
        console.log(err);
    }
});