Plans supporting Knowledge base widget
Free | Professional | Business | Enterprise |
---|---|---|---|
The URL Mapping feature within the knowledge base widget allows you to tailor the display of specific articles and categories based on the pages your end users visit. This functionality not only enhances user experience by directing users to relevant content but also enables you to hide the knowledge base widget on certain URLs or provide a search bar with custom placeholders, guiding users on what to search.
Using URL mapping
To configure URL mapping, you perform specific actions within the knowledgebase widget for designated URLs.
Actions
There are four actions you can execute with URL mapping:
Show article: Displays a single article on the specified URL.
Show list of articles: Lists selected articles under the Recommended section within the Knowledge Base widget on the specified URL.
Show search results: Allows you to set a specific search term to query your knowledge base, returning relevant search results on the specified URL.
Hide widget: Prevents the Knowledge Base widget icon from appearing on the specified URL.
You can find these actions under the URL Mapping tab or when editing an existing mapping.
NOTE
For URL Mapping to work, the Knowledge base widget must be installed within your site or app. For more information, read the article on Installing the Knowledge base widget.
URL Parameters
When configuring the Knowledge Base widget URL, you can include three types of parameters:
Include Path:
/thisis/a/path
Include Query:
?animal=bear
Include Hash:
#inbox
You can also enable the Is Regex toggle to incorporate regular expressions into your URL configurations.
Adding URL Mapping to your Widget
To integrate the desired widget into your knowledge base site, follow these steps:
Navigate to URL Mapping tab in the Widget () in the Knowledge base portal.
Click New URL mapping and specify the following:
Name - The URL Mapping name will only be shown on the URL mapping record within Document360
URL structure - Select the desired URL parameter type (Include path/Include query/Include hash). You must enable at least one URL parameter
Type in the URL on which you want the article/category to show or action to occur.
NOTE
Your domain name is not included in the URL path. For instance,
https://document360.com/ebook/rapid-guide-to-launch-your-knowledge-base/
, your URL Path would be/ebook/rapid-guide-to-launch-your-knowledge-base/
Action - Select the desired action.
Select workspace - Select the desired version (if you have multiple versions).
Language to - Select the desired language (if you have multiple languages).
Article to show - In the search bar, select the articles/categories you want to show from your knowledge base documentation.
NOTE
Folder categories are not available for selection. Only page and index category types are available for selection.
Click Create.
Once an end user accesses your specified URL path and opens the Knowledge Base widget, they will see the mapped article/category. This information remains consistent as they navigate between the Knowledge Base widget tabs within the same version and language.
Editing URL mapping
To modify an existing URL mapping:
Navigate to Widget () in the Knowledge base portal.
Hover on the desired Knowledge base widget and click the Edit () icon.
In the URL mapping tab, you can find the list of available URL mapping.
Hover over the desired URL mapping and click the Edit () icon.
The Update URL mapping blade will appear.
Update the desired information and click Update.
Deleting URL mapping
You can delete a set URL mapping.
Navigate to Widget () in the Knowledge base portal.
Hover on the desired Knowledge base widget and click the Edit () icon.
In the URL mapping tab, you can find the list of available URL mapping.
Hover over the desired URL mapping and click the Delete () icon.
Click Yes in the Delete confirmation prompt.
URL mapping settings
You can define the Knowledge base widget behavior for URLs that do not have configured mapping. Defining this behavior can improve the user experience and accessibility to the documentation.
Navigate to Widget () in the Knowledge base portal > Configure & connect.
Under Set controls section, expand the URL mapping settings section.
Select the desired option:
Navigate to the page help/knowledge base: Select this option to display the article/category in Page help or Knowledge base tab in the Widget.
Do not make any changes to the existing setup: Select this option to display the last opened article/category in the Widget.
Click Save.
Basic URL matching
Understanding URL matching is crucial for effective URL mapping. A general-purpose regex for matching typical URLs looks like this:
^https?://?[a-zA-Z0-9.-]+/[a-zA-Z0-9/._-]*??[a-zA-Z0-9=&._-]*?#[a-zA-Z0-9_-]*?$
Explanation of the components
^https?://?
: Matches the protocol (e.g.,http://
orhttps://
). The?
makes the protocol optional.NOTE
Ensure to add a backward slash (\) before every forward slash (/) while testing your URL on https://regex101.com.
[a-zA-Z0-9.-]+
: Matches the domain name, including letters, numbers, dots (.
), and hyphens (-
)./[a-zA-Z0-9/._-]*?
: Matches the path after the domain, allowing slashes, alphanumeric characters, dots, underscores, and hyphens.?[a-zA-Z0-9=&._-]*?
: Matches optional query parameters (e.g.,?key=value
), making this part optional.#[a-zA-Z0-9_-]*?
: Matches the fragment (e.g.,#section
), which is also optional.
Examples of URL mapping using Regex
Mapping URLs with specific paths
To map a URL pattern like /users/{id}
, use:
^/users/[0-9]+$
This captures a user ID dynamically.
Example Matches
/users/123
/users/456
Mapping URLs with query parameters
For URLs like /search?q={query}
, the regex would be:
^/search?q=[a-zA-Z0-9]+$
Example Matches
/search?q=apple
/search?q=123abc
Mapping URLs with optional parameters
For a URL pattern like /products/{category}/{id}
, where category is optional:
^/products/[a-zA-Z]+?/[0-9]+$
Example Matches
/products/123
/products/electronics/123
Mapping URLs with wildcard or multiple paths
For /blog/*
:
^/blog/.*?$
Example Matches
/blog
/blog/how-to-code
/blog/2021/10
Mapping URLs with subdomains
For subdomain URLs:
^https?://?[a-zA-Z0-9-]+.example.com$
Example Matches
http://blog.example.com
https://shop.example.com
Combining multiple components
To handle more complex URL mappings, you can combine the various components as needed. The comprehensive regex that matches a URL with an optional protocol, domain, path, query parameters, and fragment looks like this:
^https?://?[a-zA-Z0-9.-]+/[a-zA-Z0-9/._-]*??[a-zA-Z0-9=&._-]*?#[a-zA-Z0-9_-]*?$
FAQ
How can I remove the Page help and Search bar from the widget when URL mapping for a single article is configured?
To remove the Page help and Search bar from the widget when URL mapping for a single article is configured:
Navigate to Widget () in the Knowledge base portal.
Hover over the desired widget and click the Edit () icon.
Paste the provided code in the Custom CSS tab:
li#page-help-tab { display: none; } .article-header .article-back-icon { display: none; } .search-container { display: none !Important; }
Paste the provided code in the Custom JavaScript tab:
setTimeout(function() { $('.search-container').hide();}, 2000); setTimeout(function() { $("#knowledge-base-tab").click();}, 2000);
Click Save.
This will hide the Page help tab and Search bar in the widget on the Knowledge base site when URL mapping for a single article is configured.