Skip to main content

Customising hub pages

A hub is the page (or lack of page) behind a sidebar category label. In this template, you configure that in sidebars.js.

info

Folders and _category_.json alone do not create hubs if the main side navigation stays manual – see Editing sidebar and TOC.

There are three common patterns, each with its specific behaviour.

PatternClicking the category labelChild topics as cardsHand-written sectionsLinkable page
Collapsible entry (no hub)Expands / collapses onlyNoNoNo
Autogenerated indexOpens a generated pageYes (automatic)Title + description onlyYes
Custom hub (index.mdx)Opens your MDX pageOptional (DocCardList)YesYes
tip

This section’s own landing page is a custom hub. Open Customising the template to see cards plus authored text.

Collapsible category (no hub page)​

info

This is the default setting for this template.

Example:

sidebars.js
{
  type: 'category',
  label: 'Creating content elements',
  items: [
    'template-description/create-content/basic-text-elements',
    'template-description/create-content/code-tables-data',
    'template-description/create-content/graphics',
  ],
},

The same pattern (no link) is used for Creating a new project from the 3di Docusaurus template, Creating content, and Reusing content.

  • No link property.
  • The label toggles children, but it doesn't navigate.
When to use

Prefer this pattern when the first child topic is a clear entry point, and you don't need a section overview.

Autogenerated index (card list)​

This is a clickable category that opens a generated overview: a page of cards from the category’s child items. You can set a title and short description, but you can't mix long authored sections with the card grid on that generated page.

This template doesn't use generated-index in the main sidebar. To add one, keep the same doc IDs you already list under a category and add a link.

Example based on the existing Reusing content group:

sidebars.js
{
  type: 'category',
  label: 'Reusing content',
  link: {
    type: 'generated-index',
    title: 'Reusing content',
    description: 'Reuse shared snippets and variables across topics.',
  },
  items: [
    'template-description/create-content/reuse-content/reusing-content-with-includes',
    'template-description/create-content/reuse-content/reusing-content-with-variables',
  ],
},
  • Chevron still expands / collapses.
  • Label click opens the generated index URL under that category.
  • Card titles and blurbs come from each child’s front matter (title, description).
When to use

Use this for a light overview with almost no maintenance: cards stay in sync when you add or remove children in sidebars.js.

Custom hub (index.mdx + DocCardList)​

Use a separate MDX topic as the category landing page when you need authored content and, optionally, the same style of child cards.

  1. Add index.mdx in the section folder (for example docs/template-description/customize-template/index.mdx).
  2. Enter the intro text, headings, and any extra sections you need.
  3. Import the card list below the frontmatter.
  4. Place the card list where the tiles should appear:
---
title: Customising the template
description: Overview of how to adapt this template.
---
import DocCardList from '@theme/DocCardList';

# Customising the template

Your hand-written intro goes here.

## Topics in this section

<DocCardList />
  1. Point the category at that doc in sidebars.js. List the child topics under items.
    Don't add the index itself, unless you want it listed twice.

Example:

sidebars.js
{
  type: 'category',
  label: 'Customising the template',
  link: {
    type: 'doc',
    id: 'template-description/customize-template/index',
  },
  items: [
    'template-description/customize-template/branding-portal',
    'template-description/customize-template/customising-home-page',
    'template-description/customize-template/customising-topic-controls',
    'template-description/customize-template/customising-hub-pages',
  ],
},

<DocCardList /> builds tiles from the current category’s sidebar children. Order follows items in sidebars.js.

Linking to a custom hub

In sidebars.js, the doc ID of a custom hub ends with /index (for example template-description/customize-template/index).

In topic body links, you need to link to the folder path instead:

[Customising the template](/docs/template-description/customize-template/)

A link that ends in /index breaks, because Docusaurus drops index from the URL.

When to use

Use a custom hub when the section needs explanation, procedures, or links beyond a card grid.

On this page: