How to Customise Knowledge Base Category Cards

Category cards appear on the main SoftwareRoad Knowledge Base page and give visitors a quick way to browse different sections of your documentation.

Each card can show the category name, description, icon or image, article count and a link to open the category.

Open the category settings

Some category card options are controlled from the plugin settings, while the category name, description and icon are managed through the category itself.

To change the overall category section:

1. Sign in to your WordPress dashboard.
2. Open Knowledge Base > Settings.
3. Select the Homepage tab.
4. Find the category settings.
5. Make your changes.
6. Select Save Changes.

To edit an individual category:

1. Open Knowledge Base > Categories.
2. Find the category you want to change.
3. Select Edit.
4. Update the category details.
5. Select Update.

Enable or disable category cards

You can choose whether categories appear on the knowledge base homepage.

To show them:

1. Open Knowledge Base > Settings > Homepage.
2. Find the option for the Categories section.
3. Enable it.
4. Select Save Changes.

If the section is disabled, your categories and articles still exist. They are simply hidden from the main knowledge base homepage.

For most knowledge bases, category cards are worth keeping because they give visitors a clear way to browse the documentation.

Change the categories heading

The heading appears above the category cards.

Examples include:

• Browse Categories
• Explore Our Documentation
• Help Topics
• Choose a Subject
• Browse the Knowledge Base
• Find Help by Category

Keep the wording short and clear.

Visitors should understand that the cards below lead to different groups of articles.

Change a category name

The category name is the main title shown on the card.

To change it:

1. Open Knowledge Base > Categories.
2. Find the category.
3. Select Edit.
4. Change the Name field.
5. Select Update.

Good category names include:

• Getting Started
• Licence and Subscription
• Creating Articles
• Customisation
• Analytics
• Troubleshooting

Avoid vague names such as General, Other or Information.

The category name should make sense without the visitor needing to read the description.

Add or change the category description

The description appears underneath the category name, depending on your current layout.

To update it:

1. Open Knowledge Base > Categories.
2. Edit the category.
3. Find the Description field.
4. Add a short explanation.
5. Select Update.

For example:

Learn how to install SoftwareRoad Knowledge Base, activate your licence and complete the first-time setup.

Keep descriptions to one or two short sentences.

Long descriptions can make one card much taller than the others and make the category grid look uneven.

Writing a useful description

A good description should explain what kind of articles are inside the category.

For example:

Licence and Subscription

Find your product key, activate your licence and learn how Monthly and Yearly subscriptions work.

This is more useful than:

Articles about licences.

Try not to repeat the category name without adding any extra information.

Add a category icon

Each category can use a Bootstrap icon.

To add one:

1. Open Knowledge Base > Categories.
2. Edit the category.
3. Find the icon field.
4. Enter a Bootstrap icon class.
5. Select Update.

Examples include:

bi-book

bi-download

bi-key

bi-gear

bi-tools

The class must include the bi- prefix.

Choose an icon that matches the category rather than simply using one that looks attractive.

Add a custom category image

You can upload a custom image instead of using a Bootstrap icon.

To add one:

1. Edit the category.
2. Find the category image option.
3. Select or upload an image from the WordPress Media Library.
4. Confirm the image.
5. Select Update.

When a custom image is selected, it takes priority over the Bootstrap icon.

Use simple images that remain easy to recognise at a smaller size.

Keep category graphics consistent

The category cards usually look best when all icons or images follow the same style.

For example, you could use:

• Bootstrap icons for every category
• Matching line-style images
• Product icons using the same colours
• Simple illustrations with transparent backgrounds

Try not to mix large photographs with small line icons.

Consistency makes the category grid easier to scan.

Change the category icon size

The general category icon size can be changed from the Design settings.

Open:

Knowledge Base > Settings > Design

Find the category icon size option and adjust it.

After saving, check several category cards rather than looking at only one.

A size that works well for a simple icon may look too large when used with a custom image.

Also check the cards on mobile.

Change the article count wording

Category cards can show how many articles are inside each category.

The wording can use placeholders such as:

{count}

and:

{article}

For example:

{count} {article}

This could display as:

1 article

or:

6 articles

Keep the placeholders in the field so the plugin can insert the correct number.

Other article count wording examples

You could use:

View {count} {article}

or:

{count} help {article}

or:

Browse {count} {article}

Keep the wording natural when there is only one article as well as when there are several.

The {article} placeholder is designed to handle the singular or plural wording.

Show or hide the category link

Depending on the current plugin version and layout, you may be able to show or hide the link or button displayed on each card.

This link opens the public category page.

Suitable wording might include:

• View Articles
• Browse Category
• Read Guides
• Explore Articles
• View Help

If the whole card is already clickable, an additional link may not be needed.

Use whichever option makes the layout easiest to understand.

Which categories appear on the homepage?

The homepage mainly displays top-level categories.

Child categories are normally organised underneath their parent category rather than shown as separate main cards.

This helps keep the homepage tidy when your knowledge base contains a larger category structure.

If a category is not appearing, check whether it has been created as a child category.

Empty categories

A category with no published articles may not appear on the homepage.

This prevents visitors from opening a category that contains no useful content.

Before expecting a card to appear, make sure:

• At least one article is published
• The article is assigned to the category
• The article is not marked as unlisted
• The category section is enabled

Arrange categories in a sensible way

Your most important categories should be easy to find.

For example, a plugin knowledge base could begin with:

1. Getting Started
2. Licence and Subscription
3. Creating Articles
4. Customisation
5. SEO and Analytics
6. Troubleshooting

Try to organise the categories around the way visitors look for help.

A visitor should not need to guess which section contains an installation or licence guide.

Avoid creating too many cards

A homepage with too many categories can become difficult to scan.

For a new knowledge base, four to eight main categories will usually be enough.

Create child categories when a main topic becomes too large rather than adding every small subject as a new homepage card.

For example, Getting Started could contain:

• Installation
• Activation
• First-Time Setup

These do not all need to be separate top-level cards.

Keep category descriptions similar in length

Cards often look more balanced when their descriptions are roughly the same length.

For example, avoid using one description with three full paragraphs while another contains only two words.

Aim for one clear sentence for each card.

This is especially important when the category cards are displayed in rows.

Use clear category colours

The main colours used by the category cards can be changed from the SoftwareRoad Knowledge Base Design settings.

Open:

Knowledge Base > Settings > Design

Review settings such as:

• Primary colour
• Category heading colour
• Icon colour
• Link colour
• Card border or background colours
• Article count colour

The exact options available depend on the plugin version.

Choose colours that match your website and provide enough contrast for the text to remain readable.

Check the category card links

After editing a category card, open the main knowledge base page and select it.

Make sure it opens the correct category page.

Also check:

• The category title
• The category description
• The article list
• Breadcrumbs
• Category contents
• Compact search, if enabled

If the card opens a 404 page, refresh the WordPress permalink rules.

Refresh WordPress permalinks

If a category URL stops working:

1. Open Settings > Permalinks.
2. Select Save Changes.
3. Clear the website cache.
4. Test the category again.

You do not normally need to change the permalink structure.

Preview the category grid

After saving your changes, open the main knowledge base page.

Check that:

• Category names are easy to read
• Descriptions are not too long
• Icons are a similar size
• Article counts look correct
• Cards line up neatly
• Links open the correct category
• The grid does not feel crowded

Check the page while signed out of WordPress so you see the public version.

Check category cards on mobile

Open the knowledge base on a phone or reduce the browser width.

Make sure that:

• Category names wrap neatly
• Descriptions remain readable
• Icons are not too large
• Cards have enough spacing
• Links are easy to tap
• No text overlaps the icon
• The article count is visible

If the cards feel too large on mobile, shorten the descriptions or reduce the icon size.

A category card is missing

If a category does not appear, check that:

• The category exists
• It is a top-level category
• At least one published article is assigned
• The article is not unlisted
• The Categories section is enabled
• The website cache has been cleared
• Your SoftwareRoad Knowledge Base licence is active

Open the category directly to make sure its public page works.

The article count is wrong

The article count may not include content that is:

• In Draft
• In Trash
• Marked as unlisted
• Assigned to another category
• Not publicly available

Check the articles assigned to the category.

Clear the website cache after publishing or moving articles.

The icon is not showing

Check that:

• The Bootstrap icon class is correct
• The class begins with bi-
• There are no extra spaces
• A custom image is not overriding it
• The category was updated
• Bootstrap Icons can load
• The website cache has been cleared

Try a simple class such as:

bi-book

The custom image is too small

The source image may contain empty transparent space around the edges.

Crop the image and upload it again.

You can also increase the category icon size under the Design settings, but remember that this may affect every category card.

The cards are different heights

Different card heights are usually caused by:

• Long category names
• Descriptions with different lengths
• Images with different proportions
• One category containing extra link text

Shorten longer descriptions and use images with similar dimensions.

A small difference is normal, especially on mobile where text wraps differently.

Changes are not appearing

If the old category card still appears:

1. Check that the category was updated.
2. Check that the plugin settings were saved.
3. Clear the WordPress cache.
4. Clear any hosting or server cache.
5. Refresh the browser.
6. Open the page in a private browser window.

Make sure you edited the correct category.

Category card checklist

Before finishing, check that:

• Each category name is clear
• Descriptions explain what visitors will find
• Icons or images match the category
• Graphics use a consistent style
• Article counts are correct
• Cards open the correct pages
• Empty categories are not being displayed
• The category grid is not overcrowded
• Cards look balanced on desktop
• Cards remain easy to use on mobile

Your category cards are now ready to help visitors browse the knowledge base.