Varia's website, varia.zone or vvvvvvaria.org
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

103 lines
2.9 KiB

# 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 <dl> 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 <dt> tags,
+ `definition`, the definition, inside <dd> 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`.