varia.website/plugins/glossary/readme.md

Glossary

Builds a glossary page containing definition lists found in articles.

Example

If you have an article (Markdown or ReST) that generates the following:

file defns.html titled "My definitions"

<dl>
  <dt>My Term</dt>
  <dd>This is definition for My Term.</dd>
  <dt>Another Term</dt>
  <dd>And another definition.</dd>
</dl>

This plugin will do two things. First, it will add an anchor to the beginning of the

tag, like so:

file defns.html titled "My definitions"

<a name="another-term"></a>
<a name="my-term"></a>
<dl>
  <dt>My Term</dt>
  <dd>This is definition for My Term.</dd>
  <dt>Another Term</dt>
  <dd>And another definition.</dd>
</dl>

Second, it will extract all such definitions and put them inside the definitions variable in the pelican context. It will be seen by all page templates.

The definitions variable will have the following attributes:

• title, the definition title, inside
  tags,
• definition, the definition, inside
  tags,
• anchor, the text inside the name attribute for the anchor link,
• source, the article or page that contains this definition list,
• see_also, containing a list of objects just like this one, made from other definitions in the same list.

For example, for the above html code, the definitions variable would look like the following:

definitions = [obj1, obj2]
obj1.title = "My Term"
obj1.definition = "This is definition for My Term."
obj1.anchor = 'my-term'
obj1.source = <Content object pointing to "My definitions" file>
obj1.see_also = [obj2]

obj2.title = "Another Term"
obj2.definition = "And another definition."
obj2.link = 'another-term'
obj2.source = <Content object pointing to "My definitions" file>
obj2.see_also = [obj1]

Usage

Next is an example usage of the definitions variable.

glossary.html

{% for def in definitions | sort(attribute='title') %}
<dl>
  <a name="{{ def.anchor }}"></a>
  <dt><h4>{{ def.title }}</h4></dt>
  <dd>
    <p>{{ def.definition }}</p>
    <p><i>
      <span>Defined in: <a href="{{ def.source.url }}#{{ def.anchor }}">{{ def.source.title }}</a>.</span>
      {% if def.see_also %}
      <span> See also: </span>
      {% for also in def.see_also %}
      <span><a href="{{ output_file }}#{{ also.anchor }}">{{ also.title }}</a>{% if not loop.last %}, {% else %}.{% endif %}</span>
      {% endfor%}
      {% endif %}
    </i></p>
  </dd>
</dl>

This example generates new anchors in the glossary page, so that navigation through the see also links is done inside the same page, as well as link to the source page (with the correct anchor too).

Stashed changes

Notes

• The glossary plugin supports the use of a GLOSSARY_EXCLUDE setting, which can be set to an arbitrary list in your pelicanconf.py. By default, it's equal to the empty list. glossary will add to definitions all definitions EXCEPT those whose title is found inside GLOSSARY_EXCLUDE.