totocaster/metalsmith-tags

A metalsmith plugin to create dedicated pages for tags in posts or pages.

Hi! I'm an app developer, designer, amateur triathlete, and photographer who loves walking.

I'm currently working in a cyber-security company as an iOS developer. There is a big chance you've heard of it. On weekends and free time that feels like programming, I work on Tride — an indie cycling and running app for all Apple products.

• 🌱 I'm currently learning digital signal processing and ML applications for activity tracking and training load predictions.
• 📫 How to reach me: @totocaster or email.
• 😄 Pronouns: he/him
• ⚡ Fun fact: I shoot a lot of photos that are not published yet, but you can see some of my snaps here.

P.S. I just discovered this GitHub feature, to be updated with more goodies soon.

metalsmith-tags's Issues

interaction between metalsmith-permalinks and metalsmith-tags

There seems to be an interaction between metalsmith-permalinks and metalsmith-tags.

metalsmith-permalinks do not works well if executed after metalsmith-tags, so I had to move the use of metalsmith-tags after the use of metalsmith-permalinks.

Is there reason for that ?

See also metalsmith/permalinks#37

use of .toString() in tests

comparing the output of toString() doesn't provide a deep comparison.

here

[{ name: 'hello', slug: 'HELLO'}, { name: 'world', slug: 'WORLD'}, { name: 'this is', slug: 'THIS IS'}, { name: 'tag', slug: 'TAG'}].toString()

returns:

[object Object],[object Object],[object Object],[object Object]

overridding path variable in pagination.files

I'm using this with metalsmith-pagination and it's somehow overriding the post metadata and removing the path variable provided by metalsmith-pagination.

long list of empty tags

I'm trying to list existing tags on a page (in order to add these tags as keywords in html header).

I'm using the following handlebars template:

<meta name="keywords" content="{{#each tags as |tag| }}{{tag.name}}{{#unless @last}}, {{/unless}}{{/each}}">

This generate the following html:

<meta name=keywords content=", , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ">

I don't understand why there is so much commas, or so much empty tag, as the page has no tag at all!

this plugin should use metalsmith-layouts instead of the deprecated metalsmith-templates plugin

I'm a happy user of metalsmith-tags and I have recently encountered a problem with this metalsmith plugin. The reason is that metalsmith-templates is a declared dependancy of metalsmith-tags. The problem is that metalsmith-templates is now deprecated (as you can read on the README file and has been replaced by metalsmith-layouts.

Do you think it could be possible to replace metalsmith-templates by metalsmith-layout ?

When I use metalsmith-tags 0.10.1, I get empty generated files (the file exist but contains no content at all) for tag pages.

How to get metadata Json in the tag pages created?

Im using metalsmith-metadata, the json metadata works for metalsmith-layouts, but for metalsmith tags ,json metadata doesnt show??
Any help?

Roadmap suggestions

After looking at the source code more closely I would like to put up the following suggested roadmap items up for discussion:

• Tag definitions in pages: Currently tags need to be provided as comma separated lists and it is not possible to use arrays or lists of tags in the frontmatter. I am not sure what the added value of comma separated lists is since they require more processing than arrays or lists.
• Pagination: The pagination basically duplicates functionality of metalsmith-pagination. It might be a good idea to remove pagination from metalsmith-tags and focus on generating the global tags metadata in a way that is compatible with metalsmith-pagination. metalsmith-tags would still be responsible for creating tag pages without pagination, but it would leave the pagination to the other plugin. The documentation would need provide an example on how to apply metalsmith-pagination afterwards.
• Add ESLint configuration: I would be great if the project includes an ESLint configuration. This would make it easier for contributors to ensure their code is neat and clean and also be helpful for maintainers when merging pull requests. I have no preference which ESLint configuration to use as long as the code is consistent. eslint-config-standard is one of many options.
• Conversion to ES2015: I think it's time to convert this project (like all other Metalsmith projects) to ES2015. This would require a Babel build step to create the npm package ES5 compliant.

Add support for YAML hyphenated array style

Could you support this style of tag array as well?

---
tags:
- grunt
- javascript

---

multi-word tags should be hyphenated

With old version of metalsmith-tags (something like 0.6.x), multi-word tags were hyphenated :

the tag my tag would be converted to my-tag

With the last version of metalsmith-tags (0.10.x or 0.11.x), tags are not hyphenated any-more.

This causes some problem, espcially when linking to the tag page. The generated page is hypenated indeed : topics/my-tag/index.html whereas the link to this page is not hyphenated topics/my tag/.

This leads to invalid links.

As a consequence, the fix should hyphenate the link to the tag 'my-tag :

<a href="/tags/my tag/">my tag</a>

should become :

<a href="/tags/my-tag/">my tag</a>

The label my tag could also be converted to my-tag or not, I don't have any strong opinion on this.

Spaces in tags are replaced by -

Spaces in tags are replaced by a dash. I guess this is done on purpose to easily generate the link to the tag page.

To avoid that, I would suggest to keep the tags intact in the document while building the tags array and to build a global tags list in the Metalsmith metadata referencing the same object as the one created for <path>/<tag>.html. This way, if you use metalsmith-permalinks, in the template you can have access to the corresponding page URL with something like tagsList[tag].path.

Bonus point, this global tags list would also allow to easily create a tag cloud (I'll have to do that in a future project).

Any though on that?

Unlisted posts with tags.

I use metalsmith-unlisted to post online posts I don't want to be public (they are not listed in the collection of posts), but still render them to share them selectively (for friends and family, for example).
And I use metalsmith-tags, well ... to tag those posts.

The problem :
When a post is unlisted and tagged, it doesn't appear in the list of posts, as expected.
But it still appears in the tag pages, so it becomes public (while I want it to be private).

I modified metalsmith-tags for this purpose, and it seems to work as expected : https://github.com/etnbrd/metalsmith-tags

But as this feature is somehow at the border between three plugins (collections, tags and unlisted), I am unsure :

• if this feature belongs to metalsmith-tags (or to metalsmith-unlisted) at the cost of adding complexity to the existing plugin,
• if I should clone metalsmith-tags, and make a new plugin with the feature (like metalsmith-tags-unlisted) at the cost of duplicating code, or
• if I should make it a separate plugin (like metalsmith-unlist-tags), but I don't know if this is possible, given that it should modify things in the middle of the tag generation.

What you think is the good direction to take ?

Thanks.

How to add links for previous and next?[Resolved by using metalsmith-paths]

Hello, I have my tag.md and tag2.md

---
title: Title
tags: first, second, third
date: 2016-09-19

---
content

&

---
title: Title
tags: first, second, third
date: 2016-09-19

---
content

This is how tags is used in build:

.use(tags({
  // yaml key for tag list in you pages
  handle: 'tags',
  // path for result pages
  path:'tags/:tag.html',
  // layout to use for tag listing
  layout:'tags.hbs',
  // provide posts sorted by 'date' (optional)
  sortBy: 'date',
  // sort direction (optional)
  reverse: true,
  // skip updating metalsmith's metadata object.
  // useful for improving performance on large blogs
  // (optional)
  skipMetadata: false,
  // Any options you want to pass to the [slug](https://github.com/dodo/node-slug) package.
  // Can also supply a custom slug function.
  // slug: function(tag) { return tag.toLowerCase() }
  slug: {mode: 'rfc3986'}
}))

My tag.hbs:

<h1>Posts for {{tag}}</h1>
<ul>{{#each pagination.files}}
  <li>{{title}}</li>
{{/each}}</ul>

<a href="{{pagination.previous.path}}">Previous</a><a href="{{pagination.next.path}}">Next</a>

But the paths in pagination.previous.path and next don't show up. How do i get the previous and next links to show up??

different tags with the same safe tag are overriding each other

When we have multiple tags with the same safe tag, one of them is overriding the other and only one page is generated.

In my opinion, when multiple tags have the same safe tag, they should be merged in the tag list.

Or the safe tag generation should generate a different tag.

This issue is in fact linked to #51 and maybe a bit to #48.

Error: Received a non-Vinyl object in `dest()`

Hello I've stumbled this error and have no idea what's wrong.

I'm using the following versions of npm and node:

$ npm --version && node --version
5.5.1
v8.9.3

I'm also using the latest version of metalsmith (2.3.0) and of metalsmith-tags (2.0.0) with gulp 4.
Here's the list of deps from package.json:

  "devDependencies": {
    "@babel/core": "^7.0.0-beta.32",
    "@babel/preset-env": "^7.0.0-beta.32",
    "@buildit/gravy": "^1.3.0",
    "babel-core": "^6.26.0",
    "babel-plugin-transform-es2015-modules-umd": "^6.24.1",
    "babel-preset-env": "^1.6.1",
    "breakpoint-sass": "^2.7.1",
    "browser-sync": "^2.18.13",
    "del": "^3.0.0",
    "eslint": "^4.3.0",
    "eslint-config-standard": "^10.2.1",
    "eslint-plugin-import": "^2.7.0",
    "eslint-plugin-node": "^5.1.1",
    "eslint-plugin-promise": "^3.5.0",
    "eslint-plugin-standard": "^3.0.1",
    "eyeglass": "^1.2.1",
    "gulp": "github:gulpjs/gulp#4.0",
    "gulp-autoprefixer": "^4.0.0",
    "gulp-babel": "^7.0.0",
    "gulp-clean-css": "^3.7.0",
    "gulp-concat": "^2.6.1",
    "gulp-filter": "^5.0.0",
    "gulp-front-matter": "^1.3.0",
    "gulp-if": "^2.0.2",
    "gulp-imagemin": "^3.3.0",
    "gulp-rename": "^1.2.2",
    "gulp-replace": "^0.6.1",
    "gulp-sass": "^3.1.0",
    "gulp-size": "^2.1.0",
    "gulp-sourcemaps": "^2.6.0",
    "gulp-uglify": "^3.0.0",
    "gulpsmith": "^0.5.5",
    "handlebars": "^4.0.10",
    "helper-moment": "^0.2.0",
    "imagemin-jpeg-recompress": "^5.1.0",
    "imagemin-pngquant": "^5.0.1",
    "metalsmith": "^2.3.0",
    "metalsmith-assets": "^0.1.0",
    "metalsmith-collections": "^0.9.0",
    "metalsmith-debug": "^1.1.0",
    "metalsmith-html-minifier": "^2.2.0",
    "metalsmith-layouts": "^1.8.1",
    "metalsmith-mapsite": "^1.0.4",
    "metalsmith-markdown": "^0.2.1",
    "metalsmith-md-summary": "0.0.1",
    "metalsmith-metallic": "^2.0.2",
    "metalsmith-permalinks": "^0.5.0",
    "metalsmith-serve": "0.0.7",
    "metalsmith-tags": "^2.0.0",
    "metalsmith-watch": "^1.0.3",
    "stylelint-config-sass-guidelines": "^3.0.1",
    "stylelint-order": "^0.6.0",
    "stylelint-scss": "^1.5.1",
    "susy": "^3.0.0",
    "swag": "^0.7.0",
    "yargs": "^8.0.2"
  },

the pipeline for metalsmith is more or less the following (reduced to the minimum where the error is still reproducible, i.e. if I disable tags and add anything else, it works fine).

function metalsmith () {
  return gulp.src(paths.pages.src)
    .pipe(fmFilter)
    .pipe(frontMatter({
      property: 'frontMatter'
    })).on('data', function (file) {
      assign(file, file.frontMatter);
      delete file.frontMatter;
    })
    .pipe(fmFilter.restore)
    .pipe(
      gulpsmith()
        .use(tags({
          'handle': 'tags',
          'path': 'tags/:tag/index.html',
          'layout': 'posts-list.hbs',
          'sortBy': 'published',
          'reverse': true,
          'skipMetadata': false,
          'slug': { 'mode': 'rfc3986' },
          'hyphenate': true
        }))        .use(debug())
    )
    .pipe(gulpIf(PRODUCTION, replace('.css', '.min.css')))
    .pipe(gulp.dest(paths.pages.dest))
    .pipe(browserSync.reload({ stream: true }));
}

the error I'm getting is the following:

[14:10:15] 'metalsmith' errored after 1.02 s
[14:10:15] Error: Received a non-Vinyl object in `dest()`
    at DestroyableTransform.normalize [as _transform] (/Users/peach/repos/blog.smartart.it-static/node_modules/vinyl-fs/lib/dest/prepare.js:16:17)
    at DestroyableTransform.Transform._read (/Users/peach/repos/blog.smartart.it-static/node_modules/readable-stream/lib/_stream_transform.js:182:10)
    at DestroyableTransform.Transform._write (/Users/peach/repos/blog.smartart.it-static/node_modules/readable-stream/lib/_stream_transform.js:170:83)
    at doWrite (/Users/peach/repos/blog.smartart.it-static/node_modules/readable-stream/lib/_stream_writable.js:406:64)
    at writeOrBuffer (/Users/peach/repos/blog.smartart.it-static/node_modules/readable-stream/lib/_stream_writable.js:395:5)
    at DestroyableTransform.Writable.write (/Users/peach/repos/blog.smartart.it-static/node_modules/readable-stream/lib/_stream_writable.js:322:11)
    at Pumpify.Duplexify._write (/Users/peach/repos/blog.smartart.it-static/node_modules/duplexify/index.js:201:22)
    at doWrite (/Users/peach/repos/blog.smartart.it-static/node_modules/readable-stream/lib/_stream_writable.js:406:64)
    at writeOrBuffer (/Users/peach/repos/blog.smartart.it-static/node_modules/readable-stream/lib/_stream_writable.js:395:5)
    at Pumpify.Writable.write (/Users/peach/repos/blog.smartart.it-static/node_modules/readable-stream/lib/_stream_writable.js:322:11)
    at DestroyableTransform.ondata (/Users/peach/repos/blog.smartart.it-static/node_modules/readable-stream/lib/_stream_readable.js:612:20)
    at emitOne (events.js:116:13)
    at DestroyableTransform.emit (events.js:211:7)
    at addChunk (/Users/peach/repos/blog.smartart.it-static/node_modules/readable-stream/lib/_stream_readable.js:284:12)
    at readableAddChunk (/Users/peach/repos/blog.smartart.it-static/node_modules/readable-stream/lib/_stream_readable.js:271:11)
    at DestroyableTransform.Readable.push (/Users/peach/repos/blog.smartart.it-static/node_modules/readable-stream/lib/_stream_readable.js:238:10)

any help would be greatly appreciated

Add list of all tags into metadata

First of all thanks for this plugin! Just like creating pages for tags, I'd like to be able to construct a tag cloud. Would you be interested in exposing tags in metadata like below:

{...
    "tags": [
        "tech": {
            "path": "/blog/tags/tech",
            "posts": [
                {file},
                {file},
                ...
            ]
        },
        "linux": { ... }
    ]
...}

use tag.name in page title

Is there a way to use tag.name in page <title>?

I'd like to add a title metadata of each page generated by the plugin. Is there a way to do that?

Error: Invalid result object from transform.

When I have the following in my article.njk template the build fails.

{% if tags %}
        <li class="posted-tags">
            {% for tag in tags %}
            <a href="{{ site.url }}/tags/{{ tag.slug }}/index.html">{{ tag.name | uppercase }}</a>
            {% endfor %}
        </li>
{% endif %}

The metadata is in place, any thoughts on why this is happening?

  metalsmith-debug-ui writing data to build +692ms
Error: Invalid result object from transform.
    at normalize (/Users/Shared/Dropbox/Projects/jcrawford.maddius/node_modules/jstransformer/index.js:64:11)
    at tryCallOne (/Users/Shared/Dropbox/Projects/jcrawford.maddius/node_modules/promise/lib/core.js:37:12)
    at /Users/Shared/Dropbox/Projects/jcrawford.maddius/node_modules/promise/lib/core.js:123:15
    at flush (/Users/Shared/Dropbox/Projects/jcrawford.maddius/node_modules/asap/raw.js:50:29)
    at process._tickCallback (internal/process/next_tick.js:61:11)
/Users/Shared/Dropbox/Projects/jcrawford.maddius/build.js:158
            throw err;
            ^

Error: Invalid result object from transform.
    at normalize (/Users/Shared/Dropbox/Projects/jcrawford.maddius/node_modules/jstransformer/index.js:64:11)
    at tryCallOne (/Users/Shared/Dropbox/Projects/jcrawford.maddius/node_modules/promise/lib/core.js:37:12)
    at /Users/Shared/Dropbox/Projects/jcrawford.maddius/node_modules/promise/lib/core.js:123:15
    at flush (/Users/Shared/Dropbox/Projects/jcrawford.maddius/node_modules/asap/raw.js:50:29)
    at process._tickCallback (internal/process/next_tick.js:61:11)
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] debug: `DEBUG=* node ./build.js`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the [email protected] debug script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/jcrawford/.npm/_logs/2019-01-03T21_33_23_020Z-debug.log

I I change tags to anything else in the for loop then the error goes away but the tags are not displayed because they don't exist at that level, such as post.tags or this.tags.

All tags metadata

It would be nice to have all (unique) tags of all files consolidated in an array.
Useful for generate a tag index page, or a tag cloud widget, or something similar.
(Particularly, I'm needing to generate a tag index page.)

article1.md file:

---
title: article 1
tags: tag-a, tag-b

---
...

article2.md file:

---
title: article 2
tags: tag-b, tag-c

---
...

In templates:

console.log(allTags); // => ['tag-a', 'tag-b', 'tag-c']

What do you think about this feature, @totocaster and @hswolff?

order tags by alphabetical order

I have a page that list all the used tags.

• Is there a way to order tags by alphabetical order?
• Is there a way to mention how many time this tag is used? For example: tag1 (4), tag2 (2), tag3 (10)
• Is there to display only tags that a used more than x times? In the example above, only tag1 and tag3 would be displayed if x=3.

Create tags as separate folder not file

Hi,

Right now tags created like files[opts.path + '/' + tag + '.html'].
What if to create them like files[opts.path + '/' + tag + '/index.html']? We can use some config option for that.

special chars are not escaped

When using special chars such as the french ç, the chat seems to be not escaped.

Hence, when listing all document containing the tag français, the page http://localhost:8080/tags/francais/ does not list the documents that contain the français tag but only the documents that contains the francais tag..

metalsmith-tags is very slow when using metalsmith-watch

I ran into major performance problems with metalsmith while using it for live development, and so I started using a little home-cooked timer to see which plugin was making a change to a single file take almost a minute and a half to rebuild. Lo and behold:

$ DEBUG=metalsmith-debug node watch
[metalsmith-watch] ✓ Live reload server started on port: 35729
  metalsmith-debug start timing +0ms
  metalsmith-debug post-metadata +1ms
  metalsmith-debug post-fileMetadata +3ms
  metalsmith-debug post-copy +16ms
  metalsmith-debug post-tags +10ms
  metalsmith-debug post-collections +23ms
  metalsmith-debug post-paginate +8s
  metalsmith-debug post-lunr +1s
  metalsmith-debug post-markdown +81ms
  metalsmith-debug post-excerpts +129ms
  metalsmith-debug post-permalinks +155ms
  metalsmith-debug post-templates +428ms
  metalsmith-debug post-assets +2ms
  metalsmith-debug post-sass +595ms
  metalsmith-debug post-prefixer +59ms
[metalsmith-serve] serving build at http://localhost:8080
[metalsmith-watch] ✔︎ Watching src/**/*
[metalsmith-watch] ✔︎ Watching assets/styles/*
[metalsmith-watch] ✔︎ Watching templates/**/*
[metalsmith-watch] ✔︎ src/blog/posts/this-is-a-post.md changed
[metalsmith-watch] - Updating 1 file...
  metalsmith-debug start timing +26s
  metalsmith-debug post-metadata +0ms
  metalsmith-debug post-fileMetadata +0ms
  metalsmith-debug post-copy +1ms
  metalsmith-debug post-tags +59s
  metalsmith-debug post-collections +0ms
  metalsmith-debug post-paginate +0ms
  metalsmith-debug post-lunr +3ms
  metalsmith-debug post-markdown +36ms
  metalsmith-debug post-excerpts +2ms
  metalsmith-debug post-permalinks +1ms
  metalsmith-debug post-templates +186ms
  metalsmith-debug post-assets +1ms
  metalsmith-debug post-sass +1ms
  metalsmith-debug post-prefixer +1ms
[metalsmith-watch] ✔︎ 12 files reloaded
[metalsmith-watch] ✔︎ src/blog/posts/this-is-a-post.md changed
[metalsmith-watch] - Updating 1 file...
  metalsmith-debug start timing +6m
  metalsmith-debug post-metadata +0ms
  metalsmith-debug post-fileMetadata +0ms
  metalsmith-debug post-copy +0ms
  metalsmith-debug post-tags +14s
  metalsmith-debug post-collections +1ms
  metalsmith-debug post-paginate +0ms
  metalsmith-debug post-lunr +2ms
  metalsmith-debug post-markdown +11ms
  metalsmith-debug post-excerpts +33ms
  metalsmith-debug post-permalinks +1ms
  metalsmith-debug post-templates +109ms
  metalsmith-debug post-assets +1ms
  metalsmith-debug post-sass +1ms
  metalsmith-debug post-prefixer +0ms
[metalsmith-watch] ✔︎ 12 files reloaded

metalsmith-tags is nice and fast on first run, and then falls off a cliff on subsequent rebuilds using metalsmith-watch. (Subsequent runs leveled off at 14s, but that's still orders of magnitude slower than any other plugin in the list.) Any guesses what's going on here?

Hangs due to duplication of posts on metadata

Using the recent 0.10 release in my metalsmith chain still leads to the above problem. It seems that the overall killer is L120, which leads to a large amount of posts getting duplicated in memory on the metadata object for each and every tag on a post.

For the last decades worth of tags/posts I have, metalsmith-tags hangs with no error output. Given I'm not using that object to my knowledge - commenting out that line does solve the issue whilst still generating the html I need. It will no longer pass tests, but could prove a workable solution for those experiencing slow/hanging issues if they don't use it later in their chain.

Want to add extra front matter to tag files.

Would you be open to a Pull Request for adding arbitrary Front Matter to the created tag files?

It might also be helpful for the values being added to be interpolated with the tag itself, but I can work around that pretty easily.

Improve Readme to say **where** you should add the .use(layouts())

I know that wise Metalsmith users are suppossed to figure this stuff out, but it would have saved me half an hour if you said "put use(tags()) after use(layouts()).

Layout template ignored

My layout template seems to be ignored/not found and presume I have a structure issue. I am able to access tags in my posts, but I am getting empty files generated in topics/:tag.html folder.

dir structure:

-/layouts/tag.hbs
-/src/posts/101.hbs
-/build.js

my script:

Metalsmith(__dirname)
    .source('./src')
    .destination('../release')
    .clean(true)
    .use(collections({posts: '*.hbs'}))
    .use(discoverPartials({
        directory: 'layouts',
        pattern: /\.hbs$/
    }))
    .use(tags({
        path: 'topics/:tag.html',
        layout: 'layouts/tag.hbs',
        skipMetadata: false,
        slug: {mode: 'rfc3986'}
    }))
    .use(inPlace({
        pattern: "**/*.hbs"
    }))
    .build(function (err) {
        if (err) throw err;
    });

tag.hbs:

<h1>Posts for {{tag}}</h1>
<ul>{{#each pagination.files}}
    <li>{{title}}</li>
{{/each}}</ul>

tags seem to be case sensitive

Tags seem to be case sensitive.

• I create a document with api tag
• I create another document with API tag

On both document, tag link is http://myserver/tags/api/.

But when I click on the link, only the first document appear, the one which have the api tag (lowercase).

So tags seem to be partially cas sensitive (the slug is lowercased, but the real tag is API or api). Is there a way to fix that?

New maintainer needed

Hello all,

I've switched my blog away from using metalsmith to render it, and as such will no longer be maintaining this project.

Looking for any maintainers to step up to champion this project forward.

-Harry