tags - Tags plugin…¶
Summary¶
This is a tags plugin. It uses Pyblosxom’s command line abilities to split generation of tags index data from display of tags index data.
It creates a $(tagslist)
variable for head and foot templates
which lists all the tags.
It creates a $(tags)
variable for story templates which lists tags
for the story.
It creates a $(tagcloud)
variable for the tag cloud.
Install¶
This plugin comes with Pyblosxom. To install, do the following:
- Add
Pyblosxom.plugins.tags
to theload_plugins
list in yourconfig.py
file. - Configure as documented below.
Configuration¶
The following config properties define where the tags file is located, how tag metadata is formatted, and how tag lists triggered.
tags_separator
This defines the separator between tags in the metadata line. Defaults to “,”.
After splitting on the separator, each individual tag is stripped of whitespace before and after the text.
For example:
Weather in Boston #tags weather, boston <p> The weather in Boston today is pretty nice. </p>returns tags
weather
andboston
.If the
tags_separator
is:py["tags_separator"] = "::"then tags could be declared in the entries like this:
Weather in Boston #tags weather::boston <p> The weather in Boston today is pretty nice. </p>
tags_filename
This is the file that holds indexed tags data. Defaults to datadir + os.pardir +
tags.index
.This file needs to be readable by the process that runs your blog. This file needs to be writable by the process that creates the index.
tags_trigger
This is the url trigger to indicate that the tags plugin should handle the file list based on the tag. Defaults totag
.
truncate_tags
If this is True, then tags index listings will get passed through the truncate callback. If this is False, then the tags index listing will not be truncated.
If you’re using a paging plugin, then setting this to True will allow your tags index to be paged.
Example:
py["truncate_tags"] = TrueDefaults to True.
In the head and foot templates, you can list all the tags with the
$(tagslist)
variable. The templates for this listing use the
following three config properties:
tags_list_start
Printed before the list. Defaults to<p>
.
tags_list_item
Used for each tag in the list. There are a bunch of variables you can use:
base_url
- the baseurl for your blogflavour
- the default flavour or flavour currently showingtag
- the tag namecount
- the number of items that are tagged with this tagtagurl
- url composed of baseurl, trigger, and tagDefaults to
<a href="%(tagurl)s">%(tag)s</a>
.
tags_list_finish
Printed after the list. Defaults to</p>
.
In the head and foot templates, you can also add a tag cloud with the
$(tagcloud)
variable. The templates for the cloud use the
following three config properties:
tags_cloud_start
Printed before the cloud. Defaults to<p>
.
tags_cloud_item
Used for each tag in the cloud list. There are a bunch of variables you can use:
base_url
- the baseurl for your blogflavour
- the default flavour or flavour currently showingtag
- the tag namecount
- the number of items that are tagged with this tagclass
- biggestTag, bigTag, mediumTag, smallTag or smallestTag–the css class for this tag representing the frequency the tag is usedtagurl
- url composed of baseurl, trigger, and tagDefaults to
<a href="%(tagurl)s">%(tag)s</a>
.
tags_cloud_finish
Printed after the cloud. Defaults to</p>
.
You’ll also want to add CSS classes for the size classes to your CSS. For example, you could add this:
.biggestTag { font-size: 16pt; }
.bigTag { font-size: 14pt }
.mediumTag { font-size: 12pt }
.smallTag { font-size: 10pt ]
.smallestTag { font-size: 8pt ]
You can list the tags for a given entry in the story template with the
$(tags)
variable. The tag items in the story are formatted with one
configuration property:
tags_item
This is the template for a single tag for an entry. It can use the following bits:
base_url
- the baseurl for this blogflavour
- the default flavour or flavour currently being viewedtag
- the tagtagurl
- url composed of baseurl, trigger and tagDefaults to
<a href="%(tagurl)s">%(tag)s</a>
.Tags are joined together with
,
.
Creating the tags index file¶
Run:
pyblosxom-cmd buildtags
from the directory your config.py
is in or:
pyblosxom-cmd buildtags --config=/path/to/config/file
from anywhere.
This builds the tags index file that the tags plugin requires to generate tags-based bits for the request.
Until you rebuild the tags index file, the entry will not have its tags indexed. Thus you should either rebuild the tags file after writing or updating an entry or you should rebuild the tags file as a cron job.
Note
If you’re using static rendering, you need to build the tags index before you statically render your blog.
Converting from categories to tags¶
This plugin has a command that goes through your entries and adds tag metadata based on the category. There are some caveats:
- it assumes entries are in the blosxom format of title, then metadata, then the body.
- it only operates on entries in the datadir.
It maintains the atime and mtime of the file. My suggestion is to back up your files (use tar or something that maintains file stats), then try it out and see how well it works, and figure out if that works or not.
To run the command do:
pyblosxom-cmd categorytotags
from the directory your config.py
is in or:
pyblosxom-cmd categorytotags --config=/path/to/config/file
from anywhere.
License¶
Plugin is distributed under license: MIT