This guide describes the options to modify the knowledge base topic layout available in MinervaKB WordPress Knowledge Base system.
Technical background. What is a topic?
In WordPress terms, KB Topic is a custom hierarchical taxonomy that allows us to categorize custom post type items (in our case, KB Articles). The simplest example of taxonomy are categories that are used to group WordPress blog posts.
What does this mean in terms of templating? According to the WordPress Template Hierarchy, themes can define custom templates for each taxonomy. If these templates are not available the theme blog archive template is used. Which leads us to the first templating option.
Using theme archive template
To switch knowledge base topics to theme template you need to enable the following option in plugin settings:
This will disable all plugin template overrides and will allow your theme to use available templates.
By default, there is no template for topics in themes, so typically this will switch to blog archive template.
If you have experience in WordPress development you can create a custom template for the topic based on your blog template or on our topic template (file category.php located in lib/templates).
Detailed topic layout
By default, a simple layout is used on the topic page. It displays a list of articles with article icons, split to multiple pages according to pagination options.
If you want to show more info for each article, you can switch to a detailed layout. Compared to the simple layout, the detailed layout also can show excerpts, number of views, likes, modified date, and more.
Topic layout can be switched in MinervaKB – Settings – Topics.
Customize layout using topic options
This approach allows you to modify specific topics. It’s often used for cases when you want to have extended top-level topics, for example in a multiproduct knowledge base.
When you open the topic edit screen in the Dashboard, you can see the various available layout options.
You can disable or enable basic layout elements, such as breadcrumbs or title and you can optionally use page content as your topic template. This allows you to use any available shortcode or page builder module you need for your layout.
Topic layout shortcodes
When using page content for the topic layout you can use the following text shortcodes to display default topic page elements:
- Title: [mkb-tmpl-topic-title]
- Description: [mkb-tmpl-topic-description]
- Breadcrumbs: [mkb-tmpl-topic-breadcrumbs]
- Search: [mkb-tmpl-topic-search]
- Child Topics: [mkb-tmpl-topic-children]
- Articles: [mkb-tmpl-topic-loop]
- Pagination: [mkb-tmpl-topic-pagination]
These shortcodes do not have options and display the same layout elements that are available in the default plugin topic layout. They only work on the topic page.
Custom elements order
If you simply want to change the order of topic page elements, you can do so using the custom order page layout (available from v1.6.8).
This allows you to reorder or remove topic page elements using drag n drop. Previously you’d have to modify WordPress actions to achieve this.
Using page content template globally
Another addition in version 1.6.8 is an option to use page content for topics globally. This works similar to using page content for a specific topic but affects all topics.
Note, that topic options have higher priority than global settings. For example, if you use reorder or custom page option globally, but have selected to use different page content for a specific topic, the topic options will override global settings.
Why page content?
Many customers have asked for more topic display options or some possibility to add custom elements. This is especially important when topics are used for products, which need much more information.
We’ve tried different approaches and decided that using page content is the most powerful and flexible option.
While it has it’s drawbacks (for example, you need to create draft pages which are not actually used as pages, the page preview looks a bit different), there’s simply no way we can match the options available using page builders, such as Elementor, Divi or other (and dozens of extensions).
Even using default WordPress Gutenberg blocks provides way more options, than any layout editing we can provide from topic or plugin settings.
What is even more important, people are familiar with these builders and don’t have to learn new UI options.
On the other hand, we cannot integrate these editors into our global or topic settings. There’s no interface to achieve this. That’s why instead of developing yet another page builder we’ve decided to provide our default topic elements as text shortcodes to be used in your preferred page builder or editor.