Tag your pages with custom taxonomies and generate archives and landing pages for your taxonomy groups.
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.
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.
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).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:
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.
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'
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'
---
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")