# Lektor Tags Plugin
[](https://pypi.org/project/lektor-tags/)
<a href="https://github.com/ambv/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
## Introduction
This 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 your `content/blog` directory tagged with `coffee` and `tea`:
```
name: First Post
---
tags:
coffee
tea
```
The `lektor-tags` plugin builds pages at these URLs:
* `/blog/tag/coffee/`
* `/blog/tag/tea/`
Each page can list all the posts with that tag.
## Installation
Add lektor-tags to your project from command line:
```shell
lektor plugins add lektor-tags
```
See [the Lektor documentation for more instructions on installing plugins](https://www.getlektor.com/docs/plugins/).
## Overview
Say you have a "blog-post" model like this:
```ini
[model]
name = Blog Post
[fields.tags]
type = strings
```
Make a `blog-post.html` template that includes:
```html
{% if this.tags %}
<ul>
{% for t in this.tags -%}
<li>
<a href="{{ ('/blog@tag/' ~ t)|url }}">
All posts tagged {{ t }}
</a>
</li>
{% endfor %}
</ul>
{% endif %}
```
This expression in the template generates a *source path* for each of the blog post's tags:
```jinja
'/blog@tag/' ~ t
```
Then if the tag is "my-tag", the expression renders a source path like:
```
/blog/tag/my-tag
```
A Lektor source path becomes an actual URL using the `url` filter. 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 through `url` to generate an actual link from the blog post to a tag page.
## Configuration
Set these options in `configs/tags.ini`:
### `parent`
Required. The source path of the tag pages' parent page. For example:
```ini
parent = /blog
```
Then tag pages' source paths are like:
```
/blog/tag/my-tag
```
You can specify the root as the parent:
```ini
parent = /
```
### `items`
A query for all items on the page for one tag. You can use the variables `site` and `tag`. The template's `this` variable has a `parent` attribute. The default query is:
```ini
items = this.parent.children.filter(F.tags.contains(tag))
```
You can sort and filter with any expression:
```ini
items = this.parent.children.filter(F.tags.contains(tag) and F.status == 'published').order_by('-pub_date')
```
If the parent page has [a pagination query](https://www.getlektor.com/docs/guides/pagination/) you may want to use it for tagged pages:
```ini
items = this.parent.pagination.items.filter(F.tags.contains(tag))
```
See [the Lektor documentation for queries](https://www.getlektor.com/docs/api/db/query/).
### `tags_field`
The name of the field in your model that contains tags. Defaults to `tags`. The field should be of type `strings`. See [the Lektor documentation for the `strings` type](https://www.getlektor.com/docs/api/db/types/strings/).
For example, if your model is like:
```ini
[fields.labels]
type = strings
```
Then add this to `tags.ini`:
```ini
tags_field = labels
```
### `template`
The template for the page that lists all posts with a certain tag. The template's `this` variable has attributes `tag` and `items`. An example template:
```html
<h1>Tag: {{ this.tag }}</h1>
<h1>Items:</h1>
<ul>
{% for i in this.items %}
<li><a href="{{ i|url }}">{{ i._id }}</a></li>
{% else %}
<li><em>No items.</em></li>
{% endfor %}
</ul>
```
Save a file like this to your project's `templates/tags.html`. If you name the file something different, like `label.html`, add this line to `tags.ini`:
```ini
template = label.html
```
The plugin provides a default template if you don't specify one.
### `url_path`
An expression for the location of each tag page. You can use the variables `site` and `tag`. The `this` variable is a page with attributes `parent` and `items`. The default expression is:
```ini
url_path = {{ this.parent.url_path }}tag/{{ tag }}
```
This expression generates URLs like `/blog/tag/coffee`.
### `ignore_missing`
Default false. To set true, add this line to `tags.ini`:
```ini
ignore_missing = true
```
This allows URLs to missing tag pages to be silently replaced with "". The example use case is if your `blog-post.html` template includes a statement like:
```html
{% for t in this.tags -%}
<a href="{{ ('/blog@tag/' ~ t)|url }}">{{ t }}</a>
{% endfor %}
```
If a blog post *draft* is not discoverable, and it has any new tags used by no published blog posts, then those tag pages do not yet exist. Turn on `ignore_missing` to 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.
### `tags`
Advanced 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:
```ini
tags = parent.children.distinct("tags")
```
If you set `tags_field` to a different field name than "tags", the default expression uses your custom field name. For example if you have this line in `tags.ini`:
```ini
tags_field = labels
```
Then the default value of `tags` is:
```ini
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:
```ini
tags = parent.children.filter(F.published).distinct("tags")
```
Or even list your tags manually:
```ini
tags = ["tag1", "tag2"]
```
See [the Lektor documentation for queries](https://www.getlektor.com/docs/api/db/query/).
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 weights
This plugin won't automatically build a tag cloud, but it provides the tools to build it.
The Jinja2 context has a `tagweights()` 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, use `count`.
- To map tags to numbers, use `log(lower, upper)`.
- To map tags to everything else, use `loggroup(list)`.
### `count` — Number of pages tagged with this tag
This is the basic weight, used as a base for the following tags.
#### Example: Tags (with tag count) sorted by tag count (most used first)
```jinja
<ul>
{% for tag, weight in (tagweights() | dictsort(by='value', reverse=true)) %}
<li>{{ tag }} ({{ weight.count }} articles).</li>
{% endfor %}
</ul>
```
### `linear` — Tags are mapped with a number between `lower` and `upper`.
The less used tag is mapped `lower`, the most used tag is mapped `upper` (`lower` and `upper` can be equal, `upper` can be smaller than `lower`).
Mapping is done using a linear function.
The result is a float: you might want to convert them to integers first (see example for `log`).
Unless you know what you are doing, you should use `log` instead.
### `log` — Logarithm of tag counts are mapped with a number between `lower` and `upper`.
The less used tag is mapped `lower`, the most used tag is mapped `upper` (`lower` and `upper` can be equal, `upper` can be smaller than `lower`).
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
```jinja
{% for tag, weight in tagweights()|dictsort %}
<a
href="{{ ('/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 argument
The 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 use `loggroup` instead.
### `loggroup` — Logarithm of tag counts are mapped with an item of the list given in argument
The 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 classes `tagcloud-tiny`, `tagcloud-small`, etc.
```jinja
{% for tag, weight in tagweights()|dictsort %}
<a
href="{{ ('/blog@tag/' ~ tag)|url }}"
class="tagcloud-{{ weight.loggroup(["tiny", "small", "normal", "big", "large"]) }}"
>
{{ tag }}
</a>
{% endfor %}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/lektor/lektor-tags",
"name": "lektor-tags",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Lektor,plugin,static-site,blog,tags",
"author": "A. Jesse Jiryu Davis",
"author_email": "jesse@emptysquare.net",
"download_url": "https://files.pythonhosted.org/packages/9d/57/a446e4041973215794f7e74af36ae62fbc250cbb5f0f03e76e78eb113af0/lektor-tags-0.5.2.tar.gz",
"platform": null,
"description": "# Lektor Tags Plugin\n\n[](https://pypi.org/project/lektor-tags/)\n<a href=\"https://github.com/ambv/black\"><img alt=\"Code style: black\" src=\"https://img.shields.io/badge/code%20style-black-000000.svg\"></a>\n\n## Introduction\n\nThis 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.\n\nFor example, if your site has blog posts in your `content/blog` directory tagged with `coffee` and `tea`:\n\n```\nname: First Post\n---\ntags:\n\ncoffee\ntea\n```\n\nThe `lektor-tags` plugin builds pages at these URLs:\n\n* `/blog/tag/coffee/`\n* `/blog/tag/tea/`\n\nEach page can list all the posts with that tag.\n\n## Installation\n\nAdd lektor-tags to your project from command line:\n\n```shell\nlektor plugins add lektor-tags\n```\n\nSee [the Lektor documentation for more instructions on installing plugins](https://www.getlektor.com/docs/plugins/).\n\n## Overview\n\nSay you have a \"blog-post\" model like this:\n\n```ini\n[model]\nname = Blog Post\n\n[fields.tags]\ntype = strings\n```\n\nMake a `blog-post.html` template that includes:\n\n```html\n{% if this.tags %}\n <ul>\n {% for t in this.tags -%}\n <li>\n <a href=\"{{ ('/blog@tag/' ~ t)|url }}\">\n All posts tagged {{ t }}\n </a>\n </li>\n {% endfor %}\n </ul>\n{% endif %}\n```\n\nThis expression in the template generates a *source path* for each of the blog post's tags:\n\n```jinja\n'/blog@tag/' ~ t\n```\n\nThen if the tag is \"my-tag\", the expression renders a source path like:\n\n```\n/blog/tag/my-tag\n```\n\nA Lektor source path becomes an actual URL using the `url` filter. So the template generates URLs to tag pages like:\n\n```\n<a href=\"{{ ('/blog@tag/' ~ t)|url }}\"></a>\n```\n\nThis uses the source path expression from before, but pipes it through `url` to generate an actual link from the blog post to a tag page.\n\n## Configuration\n\nSet these options in `configs/tags.ini`:\n\n### `parent`\n\nRequired. The source path of the tag pages' parent page. For example:\n\n```ini\nparent = /blog\n```\n\nThen tag pages' source paths are like:\n\n```\n/blog/tag/my-tag\n```\n\nYou can specify the root as the parent:\n\n```ini\nparent = /\n```\n\n### `items`\n\nA query for all items on the page for one tag. You can use the variables `site` and `tag`. The template's `this` variable has a `parent` attribute. The default query is:\n\n```ini\nitems = this.parent.children.filter(F.tags.contains(tag))\n```\n\nYou can sort and filter with any expression:\n\n```ini\nitems = this.parent.children.filter(F.tags.contains(tag) and F.status == 'published').order_by('-pub_date')\n```\n\nIf the parent page has [a pagination query](https://www.getlektor.com/docs/guides/pagination/) you may want to use it for tagged pages:\n\n```ini\nitems = this.parent.pagination.items.filter(F.tags.contains(tag))\n```\n\nSee [the Lektor documentation for queries](https://www.getlektor.com/docs/api/db/query/).\n\n### `tags_field`\n\nThe name of the field in your model that contains tags. Defaults to `tags`. The field should be of type `strings`. See [the Lektor documentation for the `strings` type](https://www.getlektor.com/docs/api/db/types/strings/).\n\nFor example, if your model is like:\n\n```ini\n[fields.labels]\ntype = strings\n```\n\nThen add this to `tags.ini`:\n\n```ini\ntags_field = labels\n```\n\n### `template`\n\nThe template for the page that lists all posts with a certain tag. The template's `this` variable has attributes `tag` and `items`. An example template:\n\n```html\n<h1>Tag: {{ this.tag }}</h1>\n<h1>Items:</h1>\n<ul>\n {% for i in this.items %}\n <li><a href=\"{{ i|url }}\">{{ i._id }}</a></li>\n {% else %}\n <li><em>No items.</em></li>\n {% endfor %}\n</ul>\n```\n\nSave a file like this to your project's `templates/tags.html`. If you name the file something different, like `label.html`, add this line to `tags.ini`:\n\n```ini\ntemplate = label.html\n```\n\nThe plugin provides a default template if you don't specify one.\n\n### `url_path`\n\nAn expression for the location of each tag page. You can use the variables `site` and `tag`. The `this` variable is a page with attributes `parent` and `items`. The default expression is:\n\n```ini\nurl_path = {{ this.parent.url_path }}tag/{{ tag }}\n```\n\nThis expression generates URLs like `/blog/tag/coffee`.\n\n### `ignore_missing`\n\nDefault false. To set true, add this line to `tags.ini`:\n\n```ini\nignore_missing = true\n```\n\nThis allows URLs to missing tag pages to be silently replaced with \"\". The example use case is if your `blog-post.html` template includes a statement like:\n\n```html\n{% for t in this.tags -%}\n <a href=\"{{ ('/blog@tag/' ~ t)|url }}\">{{ t }}</a>\n{% endfor %}\n```\n\nIf a blog post *draft* is not discoverable, and it has any new tags used by no published blog posts, then those tag pages do not yet exist. Turn on `ignore_missing` to 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.\n\n### `tags`\n\nAdvanced 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:\n\n```ini\ntags = parent.children.distinct(\"tags\")\n```\n\nIf you set `tags_field` to a different field name than \"tags\", the default expression uses your custom field name. For example if you have this line in `tags.ini`:\n\n```ini\ntags_field = labels\n```\n\nThen the default value of `tags` is:\n\n```ini\ntags = parent.children.distinct(\"labels\")\n```\n\nYou can use any template expression. For example, if your items have a \"published\" boolean field, you can select tags of published items:\n\n```ini\ntags = parent.children.filter(F.published).distinct(\"tags\")\n```\n\nOr even list your tags manually:\n\n```ini\ntags = [\"tag1\", \"tag2\"]\n```\n\nSee [the Lektor documentation for queries](https://www.getlektor.com/docs/api/db/query/).\n\nTags 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.\n\n## Tag cloud & tag weights\n\nThis plugin won't automatically build a tag cloud, but it provides the tools to build it.\n\nThe Jinja2 context has a `tagweights()` 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.\n\nUnused tags are ignored.\n\n### TL;DR Which weight function should I use?\n\n- To get the number of pages tagged by each tag, use `count`.\n- To map tags to numbers, use `log(lower, upper)`.\n- To map tags to everything else, use `loggroup(list)`.\n\n### `count` \u2014 Number of pages tagged with this tag\n\nThis is the basic weight, used as a base for the following tags.\n\n#### Example: Tags (with tag count) sorted by tag count (most used first)\n\n```jinja\n<ul>\n{% for tag, weight in (tagweights() | dictsort(by='value', reverse=true)) %}\n <li>{{ tag }} ({{ weight.count }} articles).</li>\n{% endfor %}\n</ul>\n```\n\n### `linear` \u2014 Tags are mapped with a number between `lower` and `upper`.\n\nThe less used tag is mapped `lower`, the most used tag is mapped `upper` (`lower` and `upper` can be equal, `upper` can be smaller than `lower`).\n\nMapping is done using a linear function.\n\nThe result is a float: you might want to convert them to integers first (see example for `log`).\n\nUnless you know what you are doing, you should use `log` instead.\n\n### `log` \u2014 Logarithm of tag counts are mapped with a number between `lower` and `upper`.\n\nThe less used tag is mapped `lower`, the most used tag is mapped `upper` (`lower` and `upper` can be equal, `upper` can be smaller than `lower`).\n\nMapping is done using a linear function over the logarithm of tag counts.\n\nThe result is a float: you might want to convert them to integers first (see example).\n\n#### Example: Most used tag is twice as big as least used tag\n\n```jinja\n{% for tag, weight in tagweights()|dictsort %}\n<a\n href=\"{{ ('/blog@tag/' ~ tag)|url }}\"\n style=\"font-size: {{ weight.log(100, 200)|round|int }}%;\"\n >\n {{ tag }}\n </a>\n{% endfor %}\n```\n\n### `lineargroup` \u2014 Map each tag with an item of the list given in argument\n\nThe less used tag is mapped with the first item, the most used tag is mapped with the last item.\n\nMapping is done using a linear function.\n\nUnless you know what you are doing, you should use `loggroup` instead.\n\n### `loggroup` \u2014 Logarithm of tag counts are mapped with an item of the list given in argument\n\nThe less used tag is mapped with the first item, the most used tag is mapped with the last item.\n\nMapping is done using a linear function over the logarithm of tag counts.\n\n#### Example: Tags are given CSS classes `tagcloud-tiny`, `tagcloud-small`, etc.\n\n```jinja\n{% for tag, weight in tagweights()|dictsort %}\n<a\n href=\"{{ ('/blog@tag/' ~ tag)|url }}\"\n class=\"tagcloud-{{ weight.loggroup([\"tiny\", \"small\", \"normal\", \"big\", \"large\"]) }}\"\n >\n {{ tag }}\n </a>\n{% endfor %}\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Lektor plugin to add tags.",
"version": "0.5.2",
"project_urls": {
"Homepage": "https://github.com/lektor/lektor-tags"
},
"split_keywords": [
"lektor",
"plugin",
"static-site",
"blog",
"tags"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "80b01d69f756220d5021d31a5361971917dae326dcbf22af52482d9f950688c7",
"md5": "5bfbb2e6d0cb9bf9d59612a4ad3d3631",
"sha256": "b9da9873662a785b506bcf65d47441949062a65004f5308ce84e8f23cd07ac0c"
},
"downloads": -1,
"filename": "lektor_tags-0.5.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5bfbb2e6d0cb9bf9d59612a4ad3d3631",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 9265,
"upload_time": "2023-11-11T08:19:17",
"upload_time_iso_8601": "2023-11-11T08:19:17.337758Z",
"url": "https://files.pythonhosted.org/packages/80/b0/1d69f756220d5021d31a5361971917dae326dcbf22af52482d9f950688c7/lektor_tags-0.5.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9d57a446e4041973215794f7e74af36ae62fbc250cbb5f0f03e76e78eb113af0",
"md5": "2ea129c7502c9f2c9ec106e0be3286ff",
"sha256": "d1f3a8125f052335904c60fadf866e138dd35d2f452ee05fd3f0aba1ea85fe89"
},
"downloads": -1,
"filename": "lektor-tags-0.5.2.tar.gz",
"has_sig": false,
"md5_digest": "2ea129c7502c9f2c9ec106e0be3286ff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12956,
"upload_time": "2023-11-11T08:19:30",
"upload_time_iso_8601": "2023-11-11T08:19:30.350026Z",
"url": "https://files.pythonhosted.org/packages/9d/57/a446e4041973215794f7e74af36ae62fbc250cbb5f0f03e76e78eb113af0/lektor-tags-0.5.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-11 08:19:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lektor",
"github_project": "lektor-tags",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "lektor-tags"
}
JSON
