Build and deploy beautiful documentation sites that grow with you

Build and deploy beautiful documentation sites that grow with you

OrchidTaxonomies

Tag your pages with custom taxonomies and generate archives and landing pages for your taxonomy groups.

official blog

About

Orchid supports generating archives from predefined Collections, and also for user-defined taxonomies inspired by Hugo. Taxonomies define logical relationships among various pages in your site, generating archives for these groups of pages to bring related content into one place.

The data that defines these logic groupings are often an intrinsic property of the page as defined by the plugin that produced it, but taxonomies may also be "tagged" by hand to give you complete flexibility over your taxonomies. This makes it easy to create archives for pages produced by another plugin, or create them yourself to match your own needs.

Demo

Usage

Predefined Collection Archives

Orchid's plugins already generate models of relationships among pages with Collections out-of-the-box, and it's common to simply want an archive of a all the pages in a given collection. For example, the OrchidPosts plugin creates collections for each blog post category, and OrchidSourceDoc creates collections for each documented module, and another collection for the READMEs for all modules.

Collection Archive Configuration

Generating one-off archives for these collections is similar to configuring Terms, as described later in this article. Simply specify the collectionType and collectionId you're already familiar with, and an archive will be generated linking to each page in that collection.

taxonomies: 
  collectionArchives:
    - collectionType: 'posts'
      collectionId: 'category1'

The collectionId parameter is optional. If missing, all collections from the given collectionType will be merged into a single archive listing.

taxonomies: 
  collectionArchives:
    - collectionType: 'posts'
      collectionId: 'category1'

In addition, you can choose to merge many disparate collections into a single archive by listing the pairs of collection parameters under the merge key. You must also specify a 'key' for these merged archives.

taxonomies: 
  collectionArchives:
  - title: 'Archives'
    key: 'archives'
    merge:
      - collectionType: 'posts'
        collectionId: 'category1'
      - collectionType: 'pages'
        collectionId: 'group1'

Both Taxonomy and Term archive pages can set a permalink in their configuration. Permalinks work the same as in other plugins, where path pieces starting with : or surrounded by {} will be replaced with that page's specific value. OrchidTaxonomies adds support for several additional path types that should be included in these permalinks:

  • :collectionType - the collectionType of the archive as set up in the configuration
  • :collectionId - the collectionId of the archive as set up in the configuration
  • :collectionKey - the unique key identifying this collection archive. If not defined in the configuration, it defaults to the collectionId or collectionType configuration values.
  • archiveIndex - Archives are paginated (defaulting to 100 items/page), and this path type will set the index of the archive page. The index of the first page in an archive is omitted for "prettier" URLs, and resumes with 2 on the second page (if items even need to be paginated).

User-defined Taxonomy Archives

Understanding Taxonomies

To understand how to use taxonomies, let's first look at a simple example you're probably already familiar and quite comfortable with, blog categories and tags.

In this example, we will consider the category and the tag as two different taxonomies, that is, blog posts can be logically grouped by both their categories and their tags. Specifically, as it relates to the OrchidPosts plugin, blog posts can be assigned to a single category, which may have parent categories, and it may also be given any number of tags that are unrelated to is category. This creates the logical association that a Post is in one category (which is commonly included in the URL), and it has many tags, which is used to group posts across different categories.

A user visiting your blog would expect to be able to view all the different categories on your site, whether they are included in your menu, or on a page of their own. The individual "categories" on your blog, such as "News", "Sports", or "Technology" would be considered the terms within the categories taxonomy, and a page is assigned to exactly one term, or one category. Likewise, the tags taxonomy can assign one or more tag terms to a page.

You could imagine custom taxonomies also being used for things like actors, directories, and generes being used to categorize movies (as described in the Hugo article), individual sections in your Wiki, or anything else. The OrchidTaxonomies allows you to create taxonomies of any kind, generating archives for all your taxonomies' terms, and the pages in each term.

To recap:

  • Taxonomy - A logical categorization of related content
  • Term - A specific, named value in the Taxonomy
  • Page - An individual piece of content assigned to a Term

Using Orchid Taxonomies

The OrchidTaxonomies plugin does not create any taxonomies by default, you must set them up yourself. This is done by setting the taxonomies on the taxonomies property of the taxonomies generator options object in config.yml.

There are several different ways to set up the taxonomies configuration. (1) You can set the taxonomies as a String to use the taxonomy default values; (2) you can set each list item to be a map of config values, where the key property is the taxonomy type; (3) or you can set each list item to be a map with a single property that is the taxonomy type, and whose value is a map of configuration values.

# Method (1), String as taxonomy types
taxonomies: 
  taxonomies:
    - 'categories'
    - 'tags'
# Method (2), Map with config values and `key` property as taxonomy type
taxonomies: 
  taxonomies:
    - key: 'categories'
      title: 'Blog Categories'
    - key: 'tags'
      title: 'Tags'
# Method (3), Map with only key as taxonomy type, and value as config values
taxonomies: 
  taxonomies:
    - categories: 
        title: 'Blog Categories'
    - tags:
        title: 'Tags'

Note that there is no difference between Method (2) and Method (3), it is simply a matter of preference.

Configuring Taxonomy Terms

Individual Terms within a Taxonomy may also be customized. Terms are located from your content and are not set up in config.yml. But for any term that is found in your content, optional configurations may used for it by setting the configuration as values of an object in its taxonomy configuration object. For example, if we have categories on our site for "News" and "Sports", we could configure the individual terms with the following configuration in config.yml:

taxonomies: 
  taxonomies:
    - categories: 
        title: 'Blog Categories'
        news: 
          title: 'Local News'
        sports: 
          title: 'Sports'

Assigning Pages to Terms

Taxonomies can either be set up as "single" or "multiple". In the case of categories and tags, the "tags" taxonomy is a multiple taxonomy type, since each Post can be given any number of tags. in contrast, the "categories" taxonomy is a singular taxonomy type, since each Post can only be in one specific category (for the OrchidPosts plugin, you may use "categores" as a multiple taxonomy to include each post in the archives for its own category and for all its parent categories).

In the case of the OrchidPosts plugin, once the Taxonomy is set up in config.yml no further configuration is necessary to generate the Post archives. The OrchidPosts plugin already does the work of assigning the Pages to Terms, and the OrchidTaxonomies plugin is able to use this configuration for itself (internally, it uses Reflection to call a getter on the Page, which returns the categories and tags). Other plugins may already be set up in their own manner as well, such as Wiki sections and Static Page groups, which makes it very easy to generate archives for any plugin you may be using.

If you want to assign pages to Taxonomies that are not set up by the plugin, you can simply add the Term values in the page's Front Matter. For "singular" taxonomies, the value must be a String. For "multiple" taxonomies, the value can be a String or a list of Strings.


---
categories: 'Sports'
tags:
  - 'Outdoor Sports'
  - 'Hiking'
  - 'Nature'
---

Archive Ordering

The archive pages in each Taxonomy and each taxonomy's term can be customized to suit your needs. Both the Taxonomy and Term configuration objects support an orderBy property, along with orderByDirection. orderBy is a list of properties on the items that make up the archive, and the items will be sorted in the order of those properties. For example, if we order Posts by [year, month, day], posts will ordered primarily by year. If the years are equal, then they will be ordered by month, and the same for equal month ordering by day.

For Term ordering, within a Taxonomy archive, you may wish to create a configuration for each term with an order property, and then set orderBy to order to sort the Terms in their specific, defined order. Pages can be sorted on any property, either set in their Front Matter or intrinsic to the Page, such as year, month, or day as described above (which are only available on Post pages), or anything else that is common to all pages, such as publishDate or title.

Both Taxonomy and Term archive pages can set a permalink in their configuration. Permalinks work the same as in other plugins, where path pieces starting with : or surrounded by {} will be replaced with that page's specific value. OrchidTaxonomies adds support for several additional path types that should be included in these permalinks:

  • :taxonomy - the key of the taxonomy. Used in both Taxonomy and Term archive pages
  • :term - the key of the term within a specific taxonomy. Only used in Term archive pages
  • :archiveIndex - Archives are paginated (defaulting to 100 items/page), and this path type will set the index of the archive page. The index of the first page in an archive is omitted for "prettier" URLs, and resumes with 2 on the second page (if items even need to be paginated).
dependencies {
    orchidRuntime("io.github.javaeden.orchid:OrchidTaxonomies:0.18.0")
}
<dependency>
    <groupId>io.github.javaeden.orchid</groupId>
    <artifactId>OrchidTaxonomies</artifactId>
    <version>0.18.0</version>
    <type>pom</type>
</dependency>
@file:DependsOn("io.github.javaeden.orchid:OrchidTaxonomies:0.18.0")