Package: lektor-tags
Lektor Tags PluginIntroductionThis plugin implements tagging for your site. For each of your tags, it builds a page displaying a list of items that have that tag. This can be used for standard tag-based blog navigation. With this plugin you can give any number of tags to any blog posts, and a page will be created for each tag.For example, if your site has blog posts in yourcontent/blogdirectory tagged withcoffeeandtea:name: First Post
---
tags:

coffee
teaThelektor-tagsplugin builds pages at these URLs:/blog/tag/coffee//blog/tag/tea/Each page can list all the posts with that tag.InstallationAdd lektor-tags to your project from command line:lektorpluginsaddlektor-tagsSeethe Lektor documentation for more instructions on installing plugins.OverviewSay you have a "blog-post" model like this:[model]name=Blog Post[fields.tags]type=stringsMake ablog-post.htmltemplate that includes:{% if this.tags %}<ul>{% for t in this.tags -%}<li><ahref="{{ ('/blog@tag/' ~ t)|url }}">All posts tagged {{ t }}</a></li>{% endfor %}</ul>{% endif %}This expression in the template generates asource pathfor each of the blog post's tags:'/blog@tag/' ~ tThen if the tag is "my-tag", the expression renders a source path like:/blog/tag/my-tagA Lektor source path becomes an actual URL using theurlfilter. So the template generates URLs to tag pages like:<a href="{{ ('/blog@tag/' ~ t)|url }}"></a>This uses the source path expression from before, but pipes it throughurlto generate an actual link from the blog post to a tag page.ConfigurationSet these options inconfigs/tags.ini:parentRequired. The source path of the tag pages' parent page. For example:parent=/blogThen tag pages' source paths are like:/blog/tag/my-tagYou can specify the root as the parent:parent=/itemsA query for all items on the page for one tag. You can use the variablessiteandtag. The template'sthisvariable has aparentattribute. The default query is:items=this.parent.children.filter(F.tags.contains(tag))You can sort and filter with any expression:items=this.parent.children.filter(F.tags.contains(tag) and F.status == 'published').order_by('-pub_date')If the parent page hasa pagination queryyou may want to use it for tagged pages:items=this.parent.pagination.items.filter(F.tags.contains(tag))Seethe Lektor documentation for queries.tags_fieldThe name of the field in your model that contains tags. Defaults totags. The field should be of typestrings. Seethe Lektor documentation for thestringstype.For example, if your model is like:[fields.labels]type=stringsThen add this totags.ini:tags_field=labelstemplateThe template for the page that lists all posts with a certain tag. The template'sthisvariable has attributestaganditems. An example template:<h1>Tag: {{ this.tag }}</h1><h1>Items:</h1><ul>{% for i in this.items %}<li><ahref="{{ i|url }}">{{ i._id }}</a></li>{% else %}<li><em>No items.</em></li>{% endfor %}</ul>Save a file like this to your project'stemplates/tags.html. If you name the file something different, likelabel.html, add this line totags.ini:template=label.htmlThe plugin provides a default template if you don't specify one.url_pathAn expression for the location of each tag page. You can use the variablessiteandtag. Thethisvariable is a page with attributesparentanditems. The default expression is:url_path={{ this.parent.url_path }}tag/{{ tag }}This expression generates URLs like/blog/tag/coffee.ignore_missingDefault false. To set true, add this line totags.ini:ignore_missing=trueThis allows URLs to missing tag pages to be silently replaced with "". The example use case is if yourblog-post.htmltemplate includes a statement like:{% for t in this.tags -%}<ahref="{{ ('/blog@tag/' ~ t)|url }}">{{ t }}</a>{% endfor %}If a blog postdraftis not discoverable, and it has any new tags used by no published blog posts, then those tag pages do not yet exist. Turn onignore_missingto allow such drafts to be built. The tag-page URL path will be the empty string "", until the draft is published and the tag page is created.tagsAdvanced configuration. An expression for the set of tags. Note that this expression is also useful in a template to get a list of all tags. The default expression is:tags=parent.children.distinct("tags")If you settags_fieldto a different field name than "tags", the default expression uses your custom field name. For example if you have this line intags.ini:tags_field=labelsThen the default value oftagsis:tags=parent.children.distinct("labels")You can use any template expression. For example, if your items have a "published" boolean field, you can select tags of published items:tags=parent.children.filter(F.published).distinct("tags")Or even list your tags manually:tags=["tag1", "tag2"]Seethe Lektor documentation for queries.Tags are always deduplicated. Tags are sorted in the order listed in the contents.lr / admin, allowing you to control their order manually. Since{{ tags }}simply returns a list, you can always apply any Jinja2 filter on that list such as sort, slice, or rejectattr.Tag cloud & tag weightsThis plugin won't automatically build a tag cloud, but it provides the tools to build it.The Jinja2 context has atagweights()function, which returns a dictionary that maps tags to their weight using several attributes or functions. Here are those attributes and functions, with examples of how they can be used in a template.Unused tags are ignored.TL;DR Which weight function should I use?To get the number of pages tagged by each tag, usecount.To map tags to numbers, uselog(lower, upper).To map tags to everything else, useloggroup(list).count— Number of pages tagged with this tagThis is the basic weight, used as a base for the following tags.Example: Tags (with tag count) sorted by tag count (most used first)<ul>{%fortag,weightin(tagweights()|dictsort(by='value',reverse=true))%}<li>{{tag}}({{weight.count}}articles).</li>{%endfor%}</ul>linear— Tags are mapped with a number betweenlowerandupper.The less used tag is mappedlower, the most used tag is mappedupper(loweranduppercan be equal,uppercan be smaller thanlower).Mapping is done using a linear function.The result is a float: you might want to convert them to integers first (see example forlog).Unless you know what you are doing, you should useloginstead.log— Logarithm of tag counts are mapped with a number betweenlowerandupper.The less used tag is mappedlower, the most used tag is mappedupper(loweranduppercan be equal,uppercan be smaller thanlower).Mapping is done using a linear function over the logarithm of tag counts.The result is a float: you might want to convert them to integers first (see example).Example: Most used tag is twice as big as least used tag{%fortag,weightintagweights()|dictsort%}<ahref="{{('/blog@tag/'~tag)|url}}"style="font-size:{{weight.log(100,200)|round|int}}%;">{{tag}}</a>{%endfor%}lineargroup— Map each tag with an item of the list given in argumentThe less used tag is mapped with the first item, the most used tag is mapped with the last item.Mapping is done using a linear function.Unless you know what you are doing, you should useloggroupinstead.loggroup— Logarithm of tag counts are mapped with an item of the list given in argumentThe less used tag is mapped with the first item, the most used tag is mapped with the last item.Mapping is done using a linear function over the logarithm of tag counts.Example: Tags are given CSS classestagcloud-tiny,tagcloud-small, etc.{%fortag,weightintagweights()|dictsort%}<ahref="{{('/blog@tag/'~tag)|url}}"class="tagcloud-{{weight.loggroup(["tiny","small","normal","big","large"])}}">{{tag}}</a>{%endfor%}