{"id":16485348,"url":"https://github.com/morganconrad/metalsmith-tagger","last_synced_at":"2025-08-22T10:10:40.143Z","repository":{"id":71409910,"uuid":"105175246","full_name":"MorganConrad/metalsmith-tagger","owner":"MorganConrad","description":"Metalsmith plugin to create a cross reference of YAML values, mainly for tags.","archived":false,"fork":false,"pushed_at":"2020-04-25T23:32:38.000Z","size":19,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-11T14:45:44.621Z","etag":null,"topics":["metalsmith","metalsmith-plugin","tag-cloud","tagger","tags"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MorganConrad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-28T16:55:20.000Z","updated_at":"2020-04-25T23:32:40.000Z","dependencies_parsed_at":"2023-03-17T11:15:13.589Z","dependency_job_id":null,"html_url":"https://github.com/MorganConrad/metalsmith-tagger","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MorganConrad%2Fmetalsmith-tagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MorganConrad%2Fmetalsmith-tagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MorganConrad%2Fmetalsmith-tagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MorganConrad%2Fmetalsmith-tagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MorganConrad","download_url":"https://codeload.github.com/MorganConrad/metalsmith-tagger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241261911,"owners_count":19936046,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["metalsmith","metalsmith-plugin","tag-cloud","tagger","tags"],"created_at":"2024-10-11T13:25:31.199Z","updated_at":"2025-02-28T22:41:14.631Z","avatar_url":"https://github.com/MorganConrad.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://secure.travis-ci.org/MorganConrad/metalsmith-tagger.png)](http://travis-ci.org/MorganConrad/metalsmith-tagger)\n[![License](http://img.shields.io/badge/license-MIT-A31F34.svg)](https://github.com/MorganConrad/metalsmith-tagger)\n[![NPM Downloads](http://img.shields.io/npm/dm/metalsmith-tagger.svg)](https://www.npmjs.org/package/metalsmith-tagger)\n[![Known Vulnerabilities](https://snyk.io/test/github/morganconrad/metalsmith-tagger/badge.svg)](https://snyk.io/test/github/morganconrad/metalsmith-tagger)\n[![Coverage Status](https://coveralls.io/repos/github/MorganConrad/metalsmith-tagger/badge.svg)](https://coveralls.io/github/MorganConrad/metalsmith-tagger)\n# metalsmith-tagger\nA [Metalsmith](http://www.metalsmith.io/) plugin to read tags for your posts, clean them up, place them back into your file object, and build a cross-reference file, for later use by your templater in creating a \"tag-cloud\".\n\nSimilar in goals to [metalsmith-tags](https://www.npmjs.com/package/metalsmith-tags), but,\ninstead of building many many static pages for the various tags and links to them, it builds\na single cross reference file, and places the tags within the file object.  You must followup with your preferred templater.\nA typical followup would be to use server side Javascript to show / hide relevant tags.  \n\n[Live demo here,](https://morganconrad.github.io/metalsmith-tagger/demo/) and source code included.\nIf you wish, you could use the cross reference to create your own static pages.\n\n## Why?\n\nWorks with any template engine.  metalsmith-tags seemed pretty tied to handlebars.\n\nYou can cross reference multiple \"tags\", e.g. \"tag\" and \"author\", by using tagger twice.\nYour server side JavaScript could show/hide multiple tags.  See demo.\n\n### In your pages:\n\n```\n---\ntitle: This is page with tags\ntags: tagged, page, metalsmith, plugin\nauthors: [\"Issac Newton\", \"Niels Bohr\"]  // also accepts an array\n---\n\nHello World...\n```\n\n### In your `build.js`\n\n```\n.use(tagger())        // creates cross-ref tags_cloud.html\n.use(tagger({\n   handle: \"authors\"  // creates authors_cloud.html\n   }))\n```\n\n\n### Options\n\n|Option | Default | Notes |\n|:------|:--------|:------|\n|handle        | \"tags\"                 | YAML key in source that holds the tags |\n|cleanupFn     | `(tag) =\u003e tag`         | function to run on tag names after `trim()`, default does nothing |\n|cleanHandle   | handle                 | where to put the cleaned up tag info |\n|path          | handle + \"_cloud.html\" | filename for the xref file |\n|YAML          | { }                    | additional YAML for the xref file (e.g. `{ layout: xxx.ms }` ) |\n|delimiter     | \",\"                    | delimiter to split tags\n|contentString | \"\"                     | used for the file's contentString Buffer |\n|fileFilter    | null                   | \u003ca href=\"#fileFilter\"\u003esee options.fileFilter below\u003c/a\u003e |\n|postProcess   | function() { }         | \u003ca href=\"#postProcess\"\u003epost processing, see below\u003c/a\u003e\n\n\n\u003ch4 id=\"contentString\"\u003eoptions.fileFilter\u003c/h4\u003e\ndetermines which files will be included\n - if missing, include all files.\n - if a string or Regex, only include matching filePaths.\n - if a user-provided-function, include the file when `filter(filePath, data, metalsmith)` returns true.  \n _e.g._ If you want to use [multimatch](https://www.npmjs.com/package/multimatch), pass something like `function(filePath) { return multimatch([filePath], [\"blogs/**\", ...])[0] };`\n\n\u003ch4 id=\"postProcess\"\u003eoptions.postProcess\u003c/h4\u003e\nIf present, when all done you may do your own tweaking and post processing, by providing a function\n```\noptions.postProcess(file, options, files, metalsmith);\n```\n\n\n### An annotated Cross-Reference File Example\nWe had a bunch of posts, with \"author\" and \"album\" information, about Beatles songs.\n\n```\n{\n   handles: [ 'author', 'album' ],  // what we cross referenced\n   layout: 'someLayout.ms',\n   path: 'somePath.html',\n   contents: Buffer [...],\n   author: {      // cross referenced by author\n      map: {      // author -\u003e post\n         Lennon: [ 'posts/Baby Youre a Rich Man.html', 'posts/Because.html' ],\n         McCartney: [ 'posts/Baby Youre a Rich Man.html','posts/All My Loving.html' ],\n         Berry: [ 'posts/Roll Over Beethoven.html' ],\n         Harrison: [ 'posts/Something.html' ]\n      },\n      array: [     // sorted by count.  Needed cause some template engines don't handle maps\n         { id: 'Lennon', files: [ 'posts/Baby Youre a Rich Man.html', 'posts/Because.html' ], count: 2 },\n         { id: 'McCartney', files: [ 'posts/Baby Youre a Rich Man.html','posts/All My Loving.html' ],count: 2 },\n         { id: 'Berry', files: [ 'posts/Roll Over Beethoven.html' ], count: 1 },\n         { id: 'Harrison', files: [ 'posts/Something.html' ], count: 1 }\n         ],\n      count: 6     // total count of author tags\n   },\n   album: {        // cross referenced by author\n      map: {       // **album** -\u003e post\n         'Magical Mystery Tour': [ 'posts/Baby Youre a Rich Man.html' ],\n         'With the Beatles': [ 'posts/All My Loving.html', 'posts/Roll Over Beethoven.html' ],\n         'Meet the Beatles!': [ 'posts/All My Loving.html' ],\n         'Abbey Road': [ 'posts/Because.html', 'posts/Something.html' ],\n         'The Beatles 2nd Album': [ 'posts/Roll Over Beethoven.html' ]\n      },\n      array: [     // sorted by count\n         { id: 'With the Beatles', files: [ 'posts/All My Loving.html', 'posts/Roll Over Beethoven.html' ], count: 2 },\n         { id: 'Abbey Road', files: [ 'posts/Because.html', 'posts/Something.html' ], count: 2 },\n         { id: 'Magical Mystery Tour', files: [ 'posts/Baby Youre a Rich Man.html' ], count: 1 },\n         { id: 'Meet the Beatles!', files: [ 'posts/All My Loving.html' ], count: 1 },\n         { id: 'The Beatles 2nd Album', files: [ 'posts/Roll Over Beethoven.html' ], count: 1 }\n      ],\n      count: 7      // total count of album tags\n   }\n}\n```\n\n\n### Notes, Todos, and Caveats\n\nIn the example above, the original files would have their tags (options.handle) property replaced by a nice cleaned up **array**, e.g.\n\n`tags: [ 'foo', 'bar1', 'baz1' ],`\n\nIf you don't want to overwrite the original tags, set `options.cleanHandle` and the array goes there.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmorganconrad%2Fmetalsmith-tagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmorganconrad%2Fmetalsmith-tagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmorganconrad%2Fmetalsmith-tagger/lists"}