Leonardo 36b7a59b67 fix memoization issue and update readme 8 anni fa
..
__init__.py 6298afc2f5 Create the glossary plugin, which creates a 'definitions' variable to page templates, containing all information on definition lists found on articles and pages. 8 anni fa
glossary.py 36b7a59b67 fix memoization issue and update readme 8 anni fa
readme.md 36b7a59b67 fix memoization issue and update readme 8 anni fa

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.