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.

Pattern	Clicking the category label	Child topics as cards	Hand-written sections	Linkable page
Collapsible entry (no hub)	Expands / collapses only	No	No	No
Autogenerated index	Opens a generated page	Yes (automatic)	Title + description only	Yes
Custom hub (`index.mdx`)	Opens your MDX page	Optional (`DocCardList`)	Yes	Yes

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.

info

Only use this type of landing page if absolutely necessary. 3di’s default in the information models this template is suitable for is to avoid section landing pages (use expanding nodes in the TOC instead)

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).

Custom hub (`index.mdx` + DocCardList)

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

info

Add index.mdx in the section folder (for example docs/template-description/customize-template/index.mdx).
Enter the intro text, headings, and any extra sections you need.
Import the card list below the frontmatter.
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 />

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.

Collapsible category (no hub page)​

Autogenerated index (card list)​

Custom hub (index.mdx + DocCardList)​

Related content​

Collapsible category (no hub page)

Autogenerated index (card list)

Custom hub (`index.mdx` + DocCardList)

Related content