v1.1.13

Getting Started

Welcome to the Knowledge Base documentation.

Here you will find everything you need to set up your Knowledge Base service and create a resource center that answers customers’ most popular questions and covers most customers’ self-service features.

Knowledge Base allows you to organize the most asked questions or any other helpful information by means of articles which are sorted by defined categories.

Go ahead, dive in!

Firstly, please, find our extension in My Downloadable Products section of our store. Learn how to install extension and proceed with Quick Start.

How to install the extension

  1. Backup your store's database and web directory.
  2. Login to the SSH console on your server and navigate to the root directory of the Magento 2 store.
  3. Copy installation instructions from the page My Downloadable Products to the SSH console and press ENTER.
  4. Run command php -f bin/magento module:enable Mirasvit_Core Mirasvit_Kb to enable the extension.
  5. Run command php -f bin/magento setup:upgrade to install the extension.
  6. Run command php -f bin/magento cache:clean to clean the cache.

  7. Deploy static view files

    rm -rf pub/static/*; rm -rf var/view_preprocessed/*; php -f bin/magento setup:static-content:deploy

Quick Start

Our Knowledge Base extension has quite an intuitive interface, so it can be used directly from the box.

However, there are some tips that can help you to build your information bank.

  1. Start with creating proper Category Tree that will correspond the main topics that you wish to cover. If you have multiple store views, develop separate hierarchy for each of it, and put under corresponding Root Categories.

  2. Create a set of Articles, covering each regular question you have.

  3. Turn on the displaying of both categories, and articles on the frontend using Settings, which allows you to flexibly change their appearance.

  4. Keep your information base up-to-date by adding new articles regularly, creating a comfortable information hub for your customers, and reducing most of your repetitive questions down to zero.

This should be a good beginning.

Refer to appropriate sections of our manual to have more info.

General Settings

This section describes settings that allow you to tune up Knowledge Base to your needs. They are located at Content -> Knowledge Base -> Settings, and divided into the following subsections.

  • General Settings
  • Comments

General Settings

Option Description
Base URL Sets frontend base URL for the Knowledge Base. For example, if you fill in: knowledge-base, your Base URL will be: http://example.com/knowledge-base.html
Enable Articles Rating If the option is enabled, the customers can rate the Knowledge Base articles.
Enable SEO Friendly URLs If the option is enabled, the extension will create SEO-friendly URLs for the categories and articles, based on their URL keys.
For example, if article has URL key mars and its primary category planets, then URL would be http://example.com/knowledge-base/planets/mars.html
Limit of article's links on category view page Allows you to set, how many articles should be displayed per page on Category View.
Hide article's author If this option is enabled, the article's author will be hidden at the frontend.
Hide article's date If this option is enabled, the article's date will be hidden at the frontend.
Display article amount If this option is enabled, the number of articles in categories that do not contain other categories, will be displayed
Exclude categories URL-keys from the Article URL If this option is enabled, categories URL keys will be skipped in the article's final URL. After changing this option, it is recommended to regenerate URLs for articles. See more here.

Comments

Option Description
Provider Allow customers to leave comments of articles with the selected provider.

There are three possible Provider types:

  • Facebook - allows to post and view comments via Facebook API
  • Disqus - allows to post and view comments via Disqus. This option triggers additional field Disqus Shortname, which is used for communicating with Disqus. More about shortnames can be found here.

Categories

Categories are the basic structure block, which allows you to organize your articles into a hierarchical structure for each store view you use.

  • Managing Categories
  • Creating a New Category

Managing Categories

Unlike Articles, Categories are managed from general edit view, divided into two parts:

  • Category Tree (left pane) - displays the hierarchical structure of currently defined categories.
  • Category Edit Pane (right pane) - allows to instantly edit selected categories.

Category Tree

Category Tree consists of the tree itself, and button pane:

  • Add Root Category - adds a zero-level category. It can be used only once per store view.
  • Add Subcategory - adds a subcategory of lower levels. Read more below.

The category utilizes drag-and-drop functional for moving categories from node to node. Subcategories can be moved in a bundle, e. q. if you move it - all its subnodes will be moved as well.

If you wish to remove a node, then select the proper node, and only then press the Delete button.

Creating a New Category

  1. Go to Content -> Knowledge Base -> Categories.
  2. If you need to add a new zero-level category, press the Add Root Category.
  3. If you need to add a subcategory, press the Add Subcategory button.

  4. On right pane fresh edit form will appear, divided into following sections:

    • General - contains basic information. It is the only mandatory section. All other sections are optional.
      • Title - the title of the category.
      • Is Active - indicates whether the category is enabled and displayed in the frontend.
      • Store View - store views, where this category and its children should be displayed. It appears only for Root Categories.
      • URL Key - URL key of the category, appears only for Subcategories. If not filled manually, it is generated from the title.
    • Design & Content - contains only one field - Content - where you can enter short description of current Category. It can be either plain or HTML-rich (with WYSIWYG editor).
    • Meta Information - contains metadata that will be included to the page and will improve the indexing of the corresponding frontend page. If a similar section in associated, Articles are not filled, category Meta Information will be propagated to Article pages as well.
      • Meta Title - meta title of current category.
      • Meta Keywords - meta keywords of articles from the current category. You can enter multiple keywords, separated with a comma.
      • Meta Description - meta description of articles from the current category.
  5. Press Save Category to add the category to the tree.

Note

Creating a New Category can be quite tricky for stores with multiple store views because the level of subcategory has additional meaning.

Root Category corresponds with a particular store view. So if you have English, French, and German store views, then proper Category Tree should look like this: Category Tree

Articles

Articles are basic building blocks of your Knowledge Base. Each article contains covering of specific topic or question and can be associated with one or more categories.

  • Managing Articles
  • Creating Articles

Managing Articles

All articles are located in Content > Knowledge Base > Articles grid.

It also provides two useful mass actions:

  • Delete - allows to remove selected articles.
  • Update URL - allows to re-generate articles URL without re-saving them. It is extremely useful when experimenting with URL settings and Category Tree.

Note

Depending on Magento's settings, each article URL can have a suffix.

It can be changed or turned off (by setting empty) at Configuration -> Catalog -> Search Engine Optimization -> Product URL Suffix option.

Creating a New Article

  1. Go to Content > Knowledge Base > Articles. Click the button Add New Article to bring up creation edit page. It consists of three tabs:
    • General Information
      • Title - title of the articles.
      • Text - contents of the article. It can contain both regular text and HTML-rich content - you can use for that WYSIWYG-editor, which is switched with Show/Hide Editor. In plain mode you can also insert there widgets, images and special variables.
      • URL Key - URL key of the article. It is used in generating final URL of article.
      • Is Active - indicates, whether article is enabled (e. q. displayed in frontend)
      • Sort Order - numeric value, that allow to create custom articles sorting instead of ID-based - for example, bring up promoted or most important ones.
      • Store View - store views where the article should be displayed. Please, note, that if you opted to show article to some storeview - the same should be set in corresponding Category.
      • Author - author of this article. By default contains staff user name, which initially had created article.
      • Text - contents of the article. It can contain both regular text and HTML-rich content - you can use for that WYSIWYG-editor, which is switched with Show/Hide Editor. In the plain mode, you can also insert widgets, images, and special variables there.
      • URL Key - URL key of the article. It is used in generating the final URL of the article.
      • Is Active - indicates, whether the article is enabled (e. q. displayed in frontend)
      • Sort Order - a numeric value that allows you to create custom articles sorting instead of ID-based - for example, bring up promoted or most important ones.
      • Store View - store views where the article should be displayed. Please, note that if you opted to show the article to some store view - the same should be set in the corresponding Category.
      • Author - author of this article. By default contains a staff user's name, which initially had created the article.
      • Are Rich Snippets Enabled? - Enables rich snippets for the current article. To add rich snippets correctly, you should fill in Meta Information for this article.
      • Tags - sets one or more comma-separated tags, which can be used for improving search of the article. Instead of Categories, they can provide additional semantic information. A good guide to tagging can be found here.
      • Categories - sets the Knowledge Base category for the article. You can either select one or more categories from Category Tree or create a new one using the New Category button.

        Note

        If an Article has more than one category that the first of them is a Primary category, and its URL-key will be used in the final URL generation.
    • Meta Information
      • Meta Information tab (allows you to set the Meta tags):
      • Meta Title - allows to set the meta title for the current article.
      • Meta Keywords - allows setting meta keywords for the current article.
      • Meta Description - allows you to set a meta description for the current article.
    • Rating
      • Number of Votes - allows you to set the default number of votes for the article.
      • Rating - allows setting the default value of the article's customer rating.
  2. Save the article.

Note

Additionally, each article has a hidden property - Final URL. It is not dynamic, but static - and re-generated on each article save.

Typically it consists of Base URL, set in Settings, Primary Category URL key and Article own key: http://example.com/knowledge-base/planets/venus.html

But if you wish to use the same Article in different store views, each of which has it's own Categories Tree - it will result in the wrong Final URL since Primary Category can be only one. In this case, we recommend you to turn on the option Exclude categories URL-keys from the Article URL. Once it enabled, URL's will be generated only from Article URL keys.

After you enable the option above, use the Update URL mass action from the grid to update all URLs in bulk.

How-To

How shall I integrate Knowledge Base with Help Desk MX extension

Integration should be set on Help Desk MX side, with the following steps:

  1. Make sure that Mirasvit Help Desk and Knowledge Base are both enabled.
  2. Proceed to Customers -> Help Desk MX -> Settings -> Feedback Tab and set the Search Knowledge Base Topics first option to Yes.
  3. Clean all Magento cache and re-generate static content.

After that, both Help Desk contact forms and a popup will be replaced with a simple search form that will ask for request - and will bring up ticket form only if the proposed Knowledge Base topic proved to be invalid (if they were found anyway).

Migration from Magento 1 to Magento 2

Below are examples of scripts, which may be used for transferring data from Mirasvit Knowledge Base for Magento 1 to Mirasvit Knowledge Base for Magento 2.

To use scripts, you need the help of a PHP developer. Scripts may contain bugs and may not transfer all necessary data. So you may need to fit them for your needs. Migration service is not a part of our support service. If you need the help of our team, you'll need to buy a migration service.

Click on the names of scripts below to download:

How to perform Migration

Follow these steps to correctly perform the migration:

  1. Run standard Magento 2 migration, and make sure, that customers and orders were transferred from your M1 store to M2;
  2. Make sure, that Knowledge Base for Magento 2 is installed on your M2 store.
  3. Place mirasvit_kb_m1_export.php to the root of your M1 store, and run it either:
    • From browser by opening URL http://store_m1.com/mirasvit_kb_m1_export.php, or
    • From SSH/Console: navigate to your store's root and run command php -f mirasvit_kb_m1_export.php
  4. If script returned success, the file kb_export.xml would be created in the root of the store, with all your data. Transfer it to the root of your M2 store;
  5. Place mirasvit_kb_m2_import.php to the root of your M2 store, and run it either:
    • From browser by opening URL http://store_m1.com/mirasvit_kb_m2_import.php, or
    • From SSH/Console: navigate to your store's root and run command php -f mirasvit_kb_m2_import.php
  6. Check migrated data.
  7. When the migration is completed, remove both migration scripts.

Note: The article's author exports by name in the example script

Troubleshooting

In some cases, the import script can crush on timeout or memory overloading error (due to large quantities of data). In this case, restart the import script by reloading the browser page. It will skip previously uploaded data, and proceed from the last unprocessed record.

How to upgrade the extension

To upgrade the extension, follow these steps:

  1. Backup your store's database and web directory.
  2. Login to the SSH console of your server and navigate to the root directory of the Magento 2 store.
  3. Run command composer require mirasvit/module-kb:* --update-with-dependencies to update current extension with all dependencies.

    Note

    In some cases, the command above is not applicable, or it's not possible to update just the current module, or you just need to upgrade all Mirasvit modules in a bundle. In this case, the command above will have no effect.

    Run instead composer update mirasvit/* command. It will update all Mirasvit modules installed in your store.

  4. Run command php -f bin/magento setup:upgrade to install the updates.
  5. Run command php -f bin/magento cache:clean to clean the cache.

  6. Deploy static view files

    rm -rf pub/static/*; rm -rf var/view_preprocessed/*; php -f bin/magento setup:static-content:deploy

Disabling the Extension

Temporarily Disable

To temporarily disable the extension please follow these steps:

  1. Login to the SSH console on your server and navigate to the root directory of the Magento 2 store.
  2. Run command php -f bin/magento module:disable Mirasvit_Kb to disable the extension.
  3. Log in to the Magento backend and refresh the store cache (if enabled).

Extension Removal

To uninstall the extension, please follow these steps:

  1. Login to the SSH console on your server and navigate to the root directory of the Magento 2 store.
  2. Run command composer remove mirasvit/module-kb to remove the extension.
  3. Log in to the Magento backend and refresh the store cache (if enabled).

1.1.13

(2024-09-26)

  • Empty titles and relations on the tag pages

1.1.12

(2024-09-12)

  • Child category url is not updated on the parent category saving

1.1.11

(2024-09-02)

  • Article Description contains article title

1.1.10

(2024-07-10)

  • Fallback to JQueryUI Compat activated. Your store is missing a dependency for a jQueryUI widget

1.1.9

(2023-07-06)

  • Class "Zend_Json" not found in RichSnippets.php

1.1.8

(2022-12-29)

Improve

  • Added 'Url Key' column to the article admin grid

1.1.7

(2022-12-07)

Fixed

  • Deprecated Functionality: strtolower()

1.1.6

(2022-09-05)

Fixed

  • Added canonical tags to article & category pages

1.1.5

(2022-08-16)

Fixed

  • Field 'Updated At' is changed when customer votes

1.1.4

(2022-07-04)

Improve

  • Show KB footer link for the separate store-view

1.1.3

(2022-07-04)

Improve

  • Added 'updated at' for article view page

1.1.2

(2022-06-24)

Fixed

  • 'Save Category' button doesn't work in m244

1.1.1

(2022-06-20)

Improvements

  • remove db_schema_whitelist.json

Fixed

  • added translation for category name

1.1.0

(2022-05-25)

Improvements

  • Migrate to declarative schema

1.0.79

(2022-05-04)

Fixed

  • Compatibility with m2.4.4 and php8

1.0.78

(2022-03-10)

Improvements

  • php8 compatibility

1.0.77

(2021-04-19)

Fixed

  • Article amount on the category view page is limited by page size

1.0.76

(2020-12-22)

Improvements

  • Compatibility with new core module

1.0.75

(2020-11-24)

Fixed

  • Meta title overrides the page display title

1.0.74

(2020-09-29)

Improvements

  • Misspelled fixes

1.0.73

(2020-07-30)

Improvements

  • Support of Magento 2.4

Fixed

  • renamed Setup clases removed underscore
  • search results displaying taking into account article sortOrder
  • added description for richSnippet field

1.0.72

(2020-06-04)

Improvements

  • Added rich snippets for the articles

1.0.71

(2020-04-21)

Fixed

  • Export articles to the Advanced SEO Suite Sitemap on Magento 2.3.5

1.0.70

(2020-04-21)

Fixed

  • Added sorting by position field to the search results

  • Searching for special chars

1.0.69

(2020-03-23)

Fixed

  • Error "Exception #0 (BadMethodCallException): Missing required argument $decoder of MSP\ReCaptcha\Block\Frontend\ReCaptcha"

1.0.68

(2020-03-03)

Fixed

  • Error "Fatal error: Uncaught Error: Call to a member function register() on null in ..."

1.0.67

(2020-02-28)

Improvements

1.0.66

(2019-12-11)

Improvements

  • Added short URLs and Breadcrumbs for multi-category articles

1.0.65

(2019-12-05)

Fixed

  • minor fixes

1.0.64

(2019-11-05)

Fixed

  • Search for multi-byte character
  • Deletion of the latest root category

Improvements

  • Added Knowledge Base's comments

1.0.63

(2019-08-08)

Fixed

  • articles displaying for customer groups

  • search results for store-view

1.0.62

(2019-08-05)

Fixed

  • Articles counting for category sidebar

1.0.61

(2019-07-08)

Fixed

  • Ability tags name updating

  • Unused tags deletion from DB

1.0.60

(2019-06-25)

Improvements

  • Set default search by "Relevance" on articles search page

1.0.59

(2019-06-24)

Fixed

  • Display of article by store

Improvements

  • Added option "Relevance" to Sort By on articles search page

1.0.58

(2019-05-27)

Fixed

  • Sorting of categories

1.0.55

(2019-04-17)

Fixed

  • Sorting of categories

1.0.54

(2019-03-11)

Fixed

  • Sitemap for Magento 2.3.1

1.0.53

(2019-03-11)

Fixed

  • Sitemap for Magento 2.3

1.0.52

(2019-02-18)

  • Fixed Wysiwyg editor for Magento 2.3

1.0.51

(2019-01-18)

  • Fixed incorrect sitemap URLs in Mirasvit SEO Sitemap

1.0.50

(2019-01-07)

Fixed

  • Issue with creating articles (magento 2.3)

1.0.49

(2018-11-29)

Fixed

  • Compatibility with Magento 2.3.0

1.0.48

(2018-11-16)

Fixed

  • Wrong category name in breadcrumbs and category list on article page for multi stores

Improvements

  • Added option "All Groups" to article settings

1.0.47

(2018-06-25)

Fixed

  • Search in article grid

Improvements

  • Added frontend page types

1.0.46

(2018-05-08)

Fixed

  • Make current article's category bold in sidebar
  • Template paths for KB blocks

1.0.45

(2018-04-03)

Improvements

  • Translation for Article and Category names

1.0.44

(2018-02-22)

Fixed

  • Pager's limit box duplication

1.0.43

(2018-02-15)

Improvements

  • Added event kb_article_after_load for developers.

Fixed

  • Solved possible error if we enable inline translation (message like Warning: sprintf(): Too few arguments in vendor/magento/module-email/Model/Template/Filter.php on line 1031)
  • Styles for category's paging

1.0.42

(2017-11-23)

Improvements

  • Allows to create articles with the same url per store view

1.0.41

(2017-10-19)

Features

  • Allowed to exclude categories keys in article URL

Fixed

  • Variables for category description

1.0.40

(2017-10-04)

Fixed

  • Cron sitemap generation

1.0.39

(2017-09-27)

Fixed

  • Compatibility with 2.2.0
  • Sitemap generation for multi stores

1.0.37

(2017-09-15)

Fixed

  • Sitemap generation for multi stores

1.0.36

(2017-09-04)

Fixed

  • Compatibility with Magento 2.2.0rc
  • Filter articles by customer group

1.0.35

(2017-08-30)

Improvements

  • Added ability to filter articles by customer group
  • Improved category tree displaying

1.0.33

(2017-08-03)

Fixed

  • URLs for sitemap

1.0.32

(2017-07-28)

Improvements

  • Added categories and articles to sitemap

1.0.30

(2017-07-06)

Fixed

  • Fixed wrong parent pickup on Category creation without selecting a parent

1.0.29

(2017-04-06)

Improvements

  • Ability to add additional content to category and change layout (xml)

1.0.28

(2017-03-20)

Improvements

  • Added option that allow to show amount of articles in category that does not contain other categories on category list page

1.0.27

(2017-02-20)

Fixed

  • Fixed redirect after voting on article

1.0.26

(2017-02-07)

Fixed

  • Fixed config does not store for storeview
  • Fixed article view page does not display categories
  • Fixed search does not use tags

1.0.25

(2017-02-03)

Improvements

  • Added filters to admin artilce list page

Fixed

  • Fixed styles for long article's name in sidebar
  • Fixed js error for Single store mode when saving article

1.0.24

(2016-12-23)

Improvements

  • Added ability to hide article's date
  • Moved category view link under the list of categories/articles

1.0.23

(2016-12-08)

Fixed

  • Fixed an issue when "Articles not found for store with multiple root categories"

1.0.22

(2016-11-22)

Fixed

  • Varnish compatibility
  • KB permissions position in role resource tree

1.0.21

(2016-11-08)

Fixed

  • XML errors

1.0.20

(2016-10-19)

Fixed

  • Ability to assign article to storeview

Improvements

  • Support of Magento 2.1.2

1.0.19

(2016-10-17)

Improvements

  • Added ability to assign article to storeview

Fixed

  • WYSIWYG insert variable widget

1.0.18

(2016-10-12)

Improvements

  • Use the same font-awesome.min.css for all extensions

Fixed

  • Added translation (#17)

1.0.17

(2016-09-20)

Fixed

  • Removed unnecessary paging templates

1.0.16

(2016-09-07)

Fixed

  • Latest version of font-awesome

1.0.15

(2016-09-05)

Improvements

  • Update font awesome to the latest version

1.0.14

(2016-08-31)

Improvements

  • Ability to use widgets

1.0.13

(2016-08-23)

Fixed

  • Fixed an issue when settings "Enable Articles Rating" and "Hide article's author" not working properly ()

1.0.12

(2016-08-05)

Fixed

  • Fixed an issue when 'kbase' css class is added to the body tag on every page ()

1.0.11

(2016-08-02)

Fixed

  • Fix article's category field in edit form for M 2.1.0
  • Fixed an issue when WYSIWYG contains broken images

1.0.10

(2016-07-22)

Improvements

  • Added ability to browse an existing image or upload a new image when editing knowledge base content

1.0.9

(2016-07-14)

Fixed

  • Fixed an issue when WYSIWYG is not showing

1.0.8

(2016-06-27)

Fixed

  • Fixed styles issue with categories sidebar and helpful block

1.0.7

(2016-06-24)

Improvements

  • Support of Magento 2.1.0

1.0.6

(2016-06-14)

Features

  • Ability to use facebook comments.

1.0.5

(2016-05-20)

Fixed

  • Fixed that inactive categories displaying in a list of categories

1.0.2

(2016-05-13)

Fixed

  • Fixed Article 'created at' contains wrong date

1.0.1

(2016-04-11)

Improvements

  • Category Display Mode
  • Styles

Fixed

  • Issue with menu
  • Remove field "Url Key" for root category
  • Fixed an issue with showing disabled categories
  • Fixed an issue with tags