Category index renders links to pages based on category names set in those pages.

Category index is a versatile way of building site navigation. For example, you can use category index to populate sections like “Releated concepts” and “Related tasks” when you add new concept or task topic. You don’t need to update these sections to add new links inside them. Instead, you set category names strategically in pages and let category index to present them.

Category index establishes the progression in which you find the information you want in your site. The progression is as follows: use an inverted tree structure to cover generic topics up-side and in detailed topics down-side. In this structure, down-side content is always related to up-side content. When the content is not related, a new top-level page should be created to cover the topic there. The breadcrumbs section on each page provides a way to go up in the hierarchy.

The following illustration presents the progression followed to go from one top-level page (A) to one bottom-level page (C) passing through a middle-level page (B) with links to related pages. In this scenario, category index is helped by breadcrumbs component to present the levels you are descending and provide a way to go up in the inverted tree.

When you expand a content page creating other pages, it becomes an index page for those pages it links to. It presents both content and links (e.g., See A, and B in the illustration above). In these cases, the presentation order is content first and index of links later.

Presentation template

Category index presentation template is in the _includes/base/topics.html file.

Category index presentation template expects you to pass the topics variable as argument. The topics variable holds a filtered instance of site.pages variable.

<div class="rounded bg-light p-4 mb-3">
<p>Topics having the <code>navigation</code> category set in the page preamble:</p>
<hr>
<div class="row my-4">
  <div class="col-sm-6">
    <p><a class="link-offset-3 link-offset-3-hover link-underline link-underline-opacity-25 link-underline-opacity-75-hover" href="/artwork/centos-web/jekyll-theme-centos-base/documentation/page-layout/navbar/">Navigation bar</a></p>
  </div>
  <div class="col-sm-6">
    <p><a class="link-offset-3 link-offset-3-hover link-underline link-underline-opacity-25 link-underline-opacity-75-hover" href="/artwork/centos-web/jekyll-theme-centos-base/documentation/page-layout/shortcuts/">Shortcuts</a></p>
  </div>
  <div class="col-sm-6">
    <p><a class="link-offset-3 link-offset-3-hover link-underline link-underline-opacity-25 link-underline-opacity-75-hover" href="/artwork/centos-web/jekyll-theme-centos-base/documentation/topic/">Topic</a></p>
  </div>
</div>

When you are assigning value to topics variable, it is possible to pass several | where: "categories", "<term>" constructions to narrow the result passed to base/topics.html.

Configuration file

Category index presentation template reads configuration variables from configuration files described below:

1. Site’s configuration file:

   _config.yml
   

   Set default values for both site and page-specific configuration variables.

2. Page preamble section of markdown files:

   **/*.md
   

   Set custom values for page-specific configuration variables. Page configuration variables defined in page preamble section of markdown files override page configuration variables defined in site’s configuration file.

Configuration variables

Category index configuration variables are described in the following table:

The categories properties can take any value. However, consistency in the values used is convenient to build a meaningful navigation flow. The following table describes some of the names you can set as value to categories property in your pages.

Write category names in singular form.

Setting page categories

To add a page category, add the categories property to your page preamble and set one or more category names describing your page.

---
title: This is a page with categories

categories: ["topic", "navigation"]
---

Page content.

Adding category index in a page

To add category index in a page, do the following:

1. Use Markdown or HTML markup to design the category index presentation template in your page content.

   ---
   title: This page uses markdown to layout a section for category index
   ---
   
   Page content.
   
   ## Navigation topics
   

2. Create a page content variable using liquid template language to store the list of pages you want to present in the category index filtering by page categories. For example, the following code creates the topics page content variable to store all pages having the navigation value set in the list of categories property.

   {% assign topics = site.pages | where: "categories", "navigation" %}
   

   When you are filtering, you can concatenate where several times to narrow the result final result.

   {% assign topics = site.pages | where: "categories", "navigation" | where: "categories", "topic" %}
   

3. Include base/topics.html along with the list of pages you want to present as argument:

   ---
   title: This page uses markdown to layout a section for category index
   ---
   
   {% assign topics = site.pages | where: "categories", "navigation" %}
   
   Page content.
   
   ## Navigation topics
   
   {% include base/topics.html topics=topics %}
   

Related topics