How to Add an Icon or Custom Image to a Knowledge Base Article

SoftwareRoad Knowledge Base lets you add an icon or custom image to each article.

These small graphics can help visitors recognise the type of guide they are opening, particularly when articles are shown in search results, category pages or article lists.

You can use either a Bootstrap icon or an image uploaded to your WordPress Media Library.

Open the article editor

To add an icon or image:

1. Sign in to your WordPress dashboard.
2. Open Knowledge Base > All Articles.
3. Select the article you want to edit.
4. Find the SoftwareRoad Knowledge Base article options.
5. Enter an icon class or choose a custom image.
6. Select Update.

You can also set these options while creating a new article through Knowledge Base > Add Article.

Add a Bootstrap icon

Bootstrap icons are simple line-style graphics that do not require you to upload an image file.

Find the article icon field and enter an icon class such as:

bi-file-text

Make sure the icon class includes the bi- prefix.

After saving the article, the icon will appear in supported parts of the knowledge base layout.

Useful article icon examples

Choose an icon that matches the subject of the article.

Installation guides

bi-download

bi-box-arrow-in-down

bi-hdd

Licence and activation guides

bi-key

bi-patch-check

bi-person-check

Settings and customisation

bi-gear

bi-sliders

bi-palette

Troubleshooting

bi-tools

bi-wrench-adjustable

bi-exclamation-triangle

General guides

bi-file-text

bi-book

bi-info-circle

Frequently asked questions

bi-question-circle

bi-chat-square-text

bi-lightbulb

Try to use icons with a consistent style across your knowledge base.

Change an existing article icon

To replace an icon:

1. Open Knowledge Base > All Articles.
2. Edit the article.
3. Find the article icon field.
4. Remove the current icon class.
5. Enter the new class.
6. Select Update.

Refresh the public knowledge base after saving.

You may need to clear your website cache before the new icon appears.

Upload a custom article image

You can use your own image instead of a Bootstrap icon.

To add one:

1. Open the article editor.
2. Find the custom article image option.
3. Select the button to choose an image.
4. Choose an existing image from the WordPress Media Library or upload a new one.
5. Confirm the selection.
6. Publish or update the article.

The selected image will then be used wherever the article’s custom image is supported.

What happens if both options are set?

If an article has both a Bootstrap icon and a custom image, the custom image takes priority.

The icon class can remain saved in the article settings, but it will not normally be displayed while the custom image is selected.

If you remove the custom image later, the saved Bootstrap icon can appear again.

Choosing a suitable custom image

Article images are normally displayed at a smaller size, so simple graphics work best.

Suitable choices include:

• Product icons
• Clean illustrations
• Line-style graphics
• Simple symbols
• Small screenshots with one clear subject
• Images with transparent backgrounds

Avoid using images containing lots of text or fine detail. They may be difficult to understand when displayed inside a smaller article card or search result.

Keep article graphics consistent

Try to use the same style throughout the knowledge base.

For example, you could use:

• Bootstrap icons for every article
• Matching custom product icons
• Simple line illustrations
• Graphics using the same colours
• Images with the same dimensions

A mixture of photographs, coloured illustrations and black line icons can make article lists feel uneven.

Consistency usually looks better than using a different visual style for every guide.

Article icon vs featured image

The article icon and featured image have different purposes.

Article icon

The article icon is a smaller graphic used to represent the guide in supported article lists or layouts.

Featured image

The featured image is the main image connected to the article. It may appear near the top of the page or in social sharing information.

You can use:

• An article icon only
• A featured image only
• Both
• Neither

Using both is fine, but check that the article does not feel too crowded.

Use a descriptive image filename

Before uploading a custom image, give it a useful filename.

For example:

software-road-knowledge-base-activation-icon.webp

This is clearer than:

image123.webp

Descriptive filenames make the WordPress Media Library easier to manage.

Add alternative text

When selecting the image, add suitable alternative text.

For example:

Key icon for SoftwareRoad Knowledge Base activation articles

Alternative text helps visitors using screen readers and provides context if the image does not load.

Keep it descriptive and avoid filling it with repeated keywords.

Recommended image format

WordPress supports common image formats such as:

• PNG
• JPG
• WebP

PNG or WebP will normally work well for icons and small graphics.

A transparent background can help the image blend into different knowledge base card colours.

Keep the file size small so article lists and search results continue loading quickly.

Change the article icon size

The general article icon size can be changed from the SoftwareRoad Knowledge Base design settings.

Open:

Knowledge Base > Settings > Design

Find the article icon size option and adjust it.

After saving the setting, check:

• Search results
• Category pages
• Article lists
• Desktop layout
• Mobile layout

The same size setting may affect several articles, so make sure it works well with all the icons or images you use.

Remove a custom article image

To remove the image:

1. Open the article editor.
2. Find the custom article image option.
3. Select the remove or clear button.
4. Select Update.

Removing the custom image does not delete the file from the WordPress Media Library.

If a Bootstrap icon is still saved, it may appear again automatically.

Remove the Bootstrap icon

To remove the icon:

1. Edit the article.
2. Find the article icon field.
3. Delete the icon class.
4. Select Update.

If a custom image is still selected, that image will continue to appear.

Remove both options if you do not want the article to use any icon or custom image.

The Bootstrap icon is not showing

If the icon does not appear, check that:

• The class begins with bi-
• The icon name is spelt correctly
• There are no extra spaces
• The article has been updated
• A custom image is not overriding the icon
• The website cache has been cleared
• The browser can load the icon files

Try entering a basic icon such as:

bi-file-text

If this appears, the original icon class may have been entered incorrectly.

The custom image is not showing

If the uploaded image does not appear:

• Check that it is still available in the Media Library
• Open the article and select the image again
• Save the article
• Clear the WordPress cache
• Clear the browser cache
• Check that the image URL opens normally
• Make sure you edited the correct article

You can also try uploading a fresh copy of the image.

The custom image looks too small

An image may appear too small if the original file contains empty or transparent space around its edges.

Open the source image and crop away any unnecessary space.

You can also adjust the article icon size under:

Knowledge Base > Settings > Design

Check several articles after changing the global size, as the setting may affect all article icons.

The custom image looks blurry

A blurry image normally means the original file is too small or has been compressed too heavily.

Upload a clearer version with enough resolution for the size at which it will be displayed.

The file does not need to be extremely large, but it should be larger than the final display size.

The icon appears in the editor but not publicly

If the icon is saved but not visible on the public knowledge base:

1. Check that the current layout displays article icons.
2. Clear the website and browser cache.
3. Confirm that the article is published.
4. Check that your SoftwareRoad Knowledge Base licence is active.
5. Test the article inside a category or search result.
6. Check that a custom image is not taking priority.

Some layouts may show article icons in lists without displaying them on the article page itself.

Check the article on mobile

After adding an icon or image, open the knowledge base on a phone or narrow browser window.

Make sure that:

• The image is easy to recognise
• It does not push the title out of place
• The article card is not too tall
• The icon does not overlap the excerpt
• Different article images appear at a similar size

A slightly smaller global icon size may work better if the article cards feel crowded.

Article image checklist

Before finishing, check that:

• The icon or image matches the article subject
• The Bootstrap icon class is valid
• The custom image is clear
• The graphic style matches other articles
• The file has a sensible size
• Useful alternative text has been added
• The article displays correctly on desktop
• The article displays correctly on mobile
• A custom image is not accidentally overriding the icon

The article now has a clear icon or image to help visitors recognise it.