Why do we need tags?#

Tags serve multiple purposes.

Tags have a one-to-many organization (i.e. one example can have several tags), whilethe gallery structure requires that examples are placed in only one location. This meanstags provide a secondary layer of organization and make the gallery of examples moreflexible and more user-friendly.

They allow for better discoverability, search, and browse functionality. They arehelpful for users struggling to write a search query for what they're looking for.

Hidden tags provide additional functionality for maintainers and contributors.

How to tag?#

Place the tag directive at the bottom of each page and add the tags underneath, e.g.:

..tags::   topic: tagging, purpose: reference

What gets a tag?#

Every gallery example should be tagged with:

• 1+ content tags

• structural, domain, or internal tag(s) if helpful

Tags can repeat existing forms of organization (e.g. an example is in the Animationfolder and also gets ananimation tag).

Tags are helpful to denote particularly good "byproduct" examples. E.g. the explicitpurpose of a gallery example might be to demonstrate a colormap, but it's also a gooddemonstration of a legend. Taglegend to indicate that, rather than changing thetitle or the scope of the example.

Proposing new tags#

1. Review existing tag list, looking out for similar entries (i.e.axes andaxis).

2. If a relevant tag or subcategory does not yet exist, propose it. Each tag is twoparts:subcategory:tag. Tags should be one or two words.

3. New tags should be be added when they are relevant to existing gallery entries too.Avoid tags that will link to only a single gallery entry.

4. Tags can recreate other forms of organization.

Tagging organization aims to work for 80-90% of cases. Some examples fall outside of thetagging structure. Niche or specific examples shouldn't be given standalone tags thatwon't apply to other examples.