wintersmith-tag v1.0.2
wintersmith-tag
This is a plugin for Wintersmith. It allows you to add tags to articles and list articles by tags.
For a complete example, please take a look at thecoolwei.com and its source.
How to use
Step1: install
Install globally or locally using npm
npm install [-g] wintersmith-tag
and add wintersmith-tag
to your project's config.json
{
"plugins": [
"wintersmith-tag"
]
}
Step2: set plugin options
You can specify options in config.json
{
"tag": {
"template": "tag-index.jade",
"perPage": 4
}
}
This plugin is based on the built-in paginator plugin, so it uses the paginator's options by default. The only exception is it has its own default for filename
. This is can be best understood by looking at the source code
paginatorDefaults =
template: 'index.jade' # template that renders pages
articles: 'articles' # directory containing contents to paginate
first: 'index.html' # filename/url for first page
filename: 'page/%d/index.html' # filename for rest of pages
perPage: 2 # number of articles per page
tagDefaults =
filename: 'tag/%s/%d/index.html' # => tag/:tagName/:pageNum/index.html
options = _.extend {}, paginatorDefaults, env.config.paginator, tagDefaults, env.config.tag
Step3: add tags to articles
Just add tags
to the metadata section of the article. Seperate multple tags by comma. Tag name can contain space.
---
title: Hello world
date: 2012-10-14 8:31
template: article.jade
tags: Algorithm, a happy story
---
Step4: modify your template
Several new context variables and helper funtions are available in the template now.
tagName
The tagName
variable contains the tag name that articles are filtered by.
env.helpers.getAllTags()
This function returns all tags in the project. It can be used to create a tag cloud on your frontpage, for example.
env.helpers.getArticlesByTag(tagName)
Returns all articles that has tag tagName
env.helpers.getTagHome(tagName)
Returns a page
object that reperents the first page of the article list filtered by tagName
. You can create a link to this page in template like
a(href=env.helpers.getTagHome(tagName).url)= tagName
env.helpers.getTagsFromArticle(article)
Returns an array of tags of current article.
- var tags = env.helpers.getTagsFromArticle(page)
each tag in tags
a.big-tag(href=env.helpers.getTagHome(tag).url)= tag
Step5: build & done!
wintersmith build -v
Lists of articles filtered by tags have been created successfully!
/tag/algorithm/1/index.html
/tag/algorithm/2/index.html
...