How to Use Bootstrap Icons in SoftwareRoad Knowledge Base

SoftwareRoad Knowledge Base supports Bootstrap Icons for category cards, article lists and homepage highlights.

Bootstrap Icons are simple line icons that help visitors recognise different parts of your WordPress knowledge base without requiring you to upload an image for every item.

You can use them for:

• Knowledge base categories
• Knowledge base articles
• Homepage highlights

What is a Bootstrap icon class?

Each Bootstrap icon has its own class name.

For example:

bi-book

bi-search

bi-gear

bi-key

bi-tools

You enter the class name into the relevant SoftwareRoad Knowledge Base icon field.

The plugin then displays the matching icon on the public knowledge base.

Correct icon class format

The icon class must begin with:

bi-

For example:

bi-book

Do not enter:

book

bootstrap-book

icon-book

<i class="bi-book"></i>

Only enter the class name itself.

Use an icon for a knowledge base category

Category icons appear on category cards and may also appear elsewhere in the category layout.

To add one:

1. Sign in to your WordPress dashboard.
2. Open Knowledge Base > Categories.
3. Edit the category.
4. Find the Bootstrap icon field.
5. Enter an icon class such as:

bi-book

6. Select Update.
7. Open the public knowledge base homepage.

The icon should appear on the category card.

Useful category icon examples

Here are a few examples that may work well for a WordPress knowledge base:

Category	Icon class
Getting Started	bi-rocket-takeoff
Installation	bi-download
Licence and Subscription	bi-key
Creating Articles	bi-file-earmark-text
Categories	bi-folder
Customisation	bi-palette
Analytics	bi-bar-chart
SEO	bi-search
Privacy	bi-shield-check
Troubleshooting	bi-tools

Choose an icon that helps explain the category rather than simply choosing one because it looks attractive.

Use an icon for a knowledge base article

Individual articles can also have their own Bootstrap icon.

Article icons may appear in:

• Search results
• Category article lists
• Popular Articles
• Related Articles
• Recently Updated Articles
• Recommended Articles
• Article headings

To add one:

1. Open Knowledge Base > All Articles.
2. Edit the article.
3. Find the article icon setting.
4. Enter a Bootstrap icon class.
5. Select Update.
6. Check the article in search and category lists.

Useful article icon examples

Article subject	Icon class
Installation guide	bi-download
Licence activation	bi-key
Search help	bi-search
Design settings	bi-palette
Analytics guide	bi-graph-up
Privacy guide	bi-shield-lock
Troubleshooting	bi-wrench-adjustable
WordPress settings	bi-gear
Article creation	bi-file-earmark-plus
Category setup	bi-folder-plus

You do not need to give every article a unique icon.

Using a small, consistent set often creates a cleaner design.

Use icons for homepage highlights

The three homepage highlights can each use a Bootstrap icon.

For example:

Clear Guides

bi-book

Quick Search

bi-search

Regularly Updated

bi-arrow-repeat

To change a highlight icon:

1. Open Knowledge Base > Settings.
2. Select the Homepage tab.
3. Find the Homepage Highlights section.
4. Enter the icon class for each highlight.
5. Select Save Changes.
6. Check the public knowledge base homepage.

Keep icons consistent

Bootstrap Icons all follow a similar visual style, which makes them useful for a professional WordPress knowledge base.

Try to keep the same approach throughout the site.

For example, use:

• Bootstrap Icons for all categories
• Bootstrap Icons for all homepage highlights
• A limited icon set for articles

Avoid mixing:

• Line icons
• Photographs
• Detailed illustrations
• Cartoon graphics
• Icons with very different weights

Consistency makes the documentation easier to scan.

Custom uploaded images take priority

SoftwareRoad Knowledge Base also supports uploaded custom images.

If both a Bootstrap icon and a custom image are saved, the uploaded image takes priority.

This means the Bootstrap icon will not normally appear while a custom image is selected.

This applies to areas such as:

• Category images
• Article images
• Homepage highlight images

Remove a custom image to show the Bootstrap icon

If the saved Bootstrap icon is not appearing:

1. Edit the category, article or highlight.
2. Find the custom image setting.
3. Remove or clear the uploaded image.
4. Make sure the Bootstrap icon class is still entered.
5. Save or update the item.
6. Clear the website cache.
7. Check the public page again.

The Bootstrap icon should then be used.

Why custom images take priority

Using the uploaded image first prevents the knowledge base from displaying two graphics for the same item.

It also lets you switch from a standard icon to custom branding without deleting the saved icon class.

If you later remove the image, the original Bootstrap icon can be used again.

Where the icons come from

SoftwareRoad Knowledge Base loads Bootstrap Icons from the Bootstrap Icons CDN hosted through jsDelivr.

This means the icon font and stylesheet are loaded from an external content delivery network when required.

You do not need to upload the Bootstrap Icons files manually.

What is jsDelivr?

jsDelivr is a content delivery network used to serve public web files.

SoftwareRoad Knowledge Base uses it to load the Bootstrap Icons stylesheet.

The browser requests the icon files when a visitor opens a page that uses them.

If access to jsDelivr is blocked, the icon may not appear.

Icon loading and privacy

The Bootstrap Icons stylesheet is loaded from an external CDN.

Your wider website privacy policy should accurately describe any external resources used by the site where required.

The icons themselves do not require visitors to sign in or submit information.

Your hosting, browser and CDN may still process normal technical request information when files are loaded.

Choose icons that are easy to understand

An icon should support the title beside it.

For example:

• A key for licence activation
• A magnifying glass for search
• A folder for categories
• A chart for analytics
• A shield for privacy
• A wrench for troubleshooting

Avoid using an icon with no obvious connection to the subject.

The category or article title should still make sense without the icon.

Do not rely on icons alone

Icons should support written labels, not replace them.

A visitor should not need to guess what a symbol means.

Always keep clear text for:

• Category names
• Article titles
• Highlight headings
• Buttons
• Sidebar sections

This also makes the knowledge base easier to use for visitors relying on accessibility tools.

Keep icon choices simple

A simple icon often works better than a very detailed one.

Knowledge base icons are usually displayed at a relatively small size.

Complicated artwork may become difficult to recognise in:

• Live search results
• Sidebar lists
• Mobile category cards
• Recommended article cards

Choose a clear symbol with a simple outline.

Change category icon size

To adjust category icons:

1. Open Knowledge Base > Settings.
2. Select the Design tab.
3. Find the Category Icon Size option.
4. Enter the new size.
5. Select Save Changes.

Check several category cards after changing it.

The setting affects all category icons rather than one individual category.

Change article icon size

To adjust article icons:

1. Open Knowledge Base > Settings > Design.
2. Find the Article Icon Size option.
3. Change the value.
4. Save the settings.
5. Check search results, categories and articles.

A size that looks suitable in a category list may feel too large in compact search, so test more than one location.

Change icon colours

Bootstrap icons can use the colours set in the SoftwareRoad Knowledge Base Design settings.

Depending on the location, this may include:

• Primary colour
• Category icon colour
• Article icon colour
• Highlight icon colour
• Sidebar link colour

Uploaded images keep their own colours and are not recoloured by these settings.

Icon colour does not affect uploaded images

The design colour settings only affect icons that can inherit a CSS colour.

An uploaded PNG, JPEG, SVG or WebP image uses the colours contained in the image file.

If you want an uploaded image to use a different colour, edit the source image and upload the updated version.

Check icon contrast

Make sure the icon is visible against its background.

For example:

• A white icon may disappear on a white card
• A pale grey icon may be difficult to see
• A dark icon may blend into a dark search area
• A bright colour may look harsh against a coloured card

Check each icon on both desktop and mobile.

Finding an icon class

When choosing an icon, use the Bootstrap Icons naming format.

Common keywords include:

• book
• folder
• file
• search
• key
• gear
• tools
• shield
• graph
• question
• info
• download
• upload

Once you find a suitable icon name, enter it with the bi- prefix.

For example:

bi-question-circle

Use the full class name

Some Bootstrap Icons have longer class names.

For example:

bi-file-earmark-text

bi-shield-check

bi-arrow-repeat

bi-bar-chart-line

Enter the complete class exactly as written.

A missing word or hyphen will prevent the icon from loading.

Avoid adding extra spaces

Enter:

bi-book

Do not enter:

bi-book

or:

bi-book

Extra spaces may stop the plugin from recognising the class correctly.

If an icon is not appearing, delete the field and type the class again.

Do not paste HTML into the icon field

The icon field expects a class name, not HTML.

Do not enter:

<i class="bi bi-book"></i>

Do not enter:

<span class="bi-book"></span>

Use only:

bi-book

SoftwareRoad Knowledge Base creates the required icon element automatically.

The bi prefix vs the bi- class

You may sometimes see Bootstrap Icon examples using:

bi bi-book

In SoftwareRoad Knowledge Base, the icon field should use the individual icon class:

bi-book

The plugin handles the base Bootstrap icon class itself.

Do not add several class names unless the field specifically asks for them.

Test an icon before using it everywhere

Try the icon on one category or article first.

Check:

• Whether it loads
• Whether the meaning is clear
• Whether it looks good at the saved size
• Whether the colour works
• Whether it matches other icons

Once it looks correct, use the same style across the rest of the knowledge base.

Icon appears in one place but not another

An article icon may appear in category lists but not in every layout.

This can depend on:

• The enabled feature
• The current page layout
• Whether the section supports icons
• Whether a custom image overrides it
• The plugin version
• Cached page content

Check the icon in the areas where it is designed to appear.

Icon is not showing

If a Bootstrap icon is missing, check that:

• The class begins with bi-
• The icon class is spelled correctly
• No extra spaces are present
• A custom uploaded image is not overriding it
• The category or article was updated
• The plugin settings were saved
• The website can reach the Bootstrap Icons CDN
• The website cache has been cleared

Try a simple known class such as:

bi-book

If that works, the previous class may have been incorrect.

All Bootstrap icons are missing

If no Bootstrap icons appear anywhere, the website may be unable to load the icon stylesheet.

Possible causes include:

• The jsDelivr CDN is blocked
• A firewall blocks external stylesheets
• A Content Security Policy blocks the CDN
• A privacy extension blocks the request
• A performance plugin removed the stylesheet
• The website cache contains an incomplete page

Check the browser developer tools for blocked or failed requests.

Firewall restrictions

A hosting firewall or corporate network may block requests to external CDNs.

The relevant files are loaded through jsDelivr.

Ask the website host or network administrator to check whether jsDelivr resources are being blocked.

Do not disable website security simply to load icons.

Only allow the required trusted resource where appropriate.

Content Security Policy

A Content Security Policy can restrict where the browser is allowed to load styles and fonts from.

If the policy does not allow the Bootstrap Icons CDN, the icons may not display.

The browser console may show a Content Security Policy error.

Update the policy carefully to allow the required jsDelivr stylesheet and font resources.

Only make this change if you understand your website security configuration.

Ad-blocking and privacy extensions

Some browser extensions block external resources.

If icons are missing for one visitor but appear for others, test:

• Another browser
• A private window
• The same browser with extensions disabled
• Another device
• Another network

If the icons only fail with one extension, the website itself may be working normally.

Performance and optimisation plugins

CSS optimisation can occasionally remove or delay the Bootstrap Icons stylesheet.

If icons disappear after enabling optimisation:

1. Clear all optimisation caches.
2. Exclude the Bootstrap Icons stylesheet from removal where possible.
3. Test without combined CSS.
4. Test without delayed styles.
5. Reload the page while signed out.

Do not permanently disable performance features unless you have confirmed they are causing the problem.

Use an uploaded custom image as an alternative

If your website cannot load the Bootstrap Icons CDN, you can use custom uploaded images instead.

To do this:

1. Edit the category, article or highlight.
2. Upload a suitable icon image.
3. Save or update the item.
4. Check the public page.

The uploaded image will take priority over the Bootstrap icon class.

This can also be useful when you want fully branded graphics.

Choosing custom icon files

For uploaded icons, use:

• PNG with a transparent background
• WebP with transparency
• A suitable SVG where your WordPress setup allows it
• Similar image dimensions
• Consistent visual styles

Avoid large photographs or images with lots of empty space.

The icon should remain clear when displayed at a small size.

Transparent backgrounds

A transparent background normally works best for category and article icons.

A white square background may look awkward on a coloured card.

Before uploading, check the image against both light and dark backgrounds if your design uses them.

Icon files and website speed

Keep uploaded images reasonably small.

A tiny knowledge base icon does not need to be a large high-resolution file.

Resize and compress images before uploading them.

Bootstrap Icons are usually lightweight because they are loaded from a shared icon font rather than separate image files.

Bootstrap Icons and SEO

Icons do not replace clear article titles, category names or written content.

For a well-organised WordPress knowledge base:

• Use descriptive category names
• Use specific article titles
• Add useful excerpts
• Use icons only as visual support

Search engines and visitors rely mainly on the written content.

Avoid adding keyword-heavy filenames or descriptions solely for SEO.

Bootstrap Icons and accessibility

The visible text beside the icon should explain the destination or subject.

Do not use an icon as the only way to communicate important information.

For example, use:

Licence and Subscription

with a key icon.

Do not show only a key icon with no label.

Clear text improves accessibility and avoids confusion.

Check icons on mobile

On a phone or tablet, make sure:

• Category icons are not too large
• Article icons do not crowd titles
• Icons remain aligned with text
• Highlight icons fit comfortably
• Uploaded images are not blurry
• Cards do not become unnecessarily tall

Reduce the global icon size if the mobile layout feels crowded.

Check icons in search results

Run a knowledge base search and review the live results.

Check that:

• Article icons are visible
• Titles have enough space
• Excerpts remain readable
• Uploaded images are not stretched
• Icons use a consistent size

Search results need to remain quick and easy to scan.

Check icons in sidebars

Some article links in the sidebar may not display icons, depending on the layout.

Where icons are shown, make sure they do not make the sidebar too wide.

The article title should remain the main focus.

Changes are not appearing

After changing an icon:

1. Select Update or Save Changes.
2. Clear the WordPress cache.
3. Clear any hosting or server cache.
4. Clear your browser cache.
5. Open the page in a private browser window.

Cached category cards and search results may continue showing the old icon.

Bootstrap icon checklist

Before finishing, check that:

• Each class begins with bi-
• Only the icon class is entered
• No HTML has been pasted into the field
• Category icons match their subjects
• Article icons are clear at a small size
• Homepage highlight icons use a consistent style
• Custom uploaded images are only used where needed
• Uploaded images take priority as expected
• Icon sizes work across desktop and mobile
• Icon colours provide enough contrast
• The website can reach the jsDelivr CDN
• Firewalls and Content Security Policy rules have been checked
• The public knowledge base has been tested while signed out

Bootstrap Icons are now ready to provide a clear and consistent visual style across your SoftwareRoad Knowledge Base.