How to build a knowledge base in SharePoint

This post will detail step-by-step how to build a knowledge base using the modern authoring experience in SharePoint Online.

Contents

Intro

SharePoint and knowledge bases have gone hand in hand for many years. If you have been involved with SharePoint for any length of time it is not an uncommon request to be asked to build a knowledge base at some point. With the advent of AI and machine learning within Microsoft 365, plus the introduction of Knowledge & Content Services (formerly Project Cortex), SharePoint Syntex and Microsoft Viva Topics, you may think the need to build a traditional knowledge base has gone the way of the dodo.

Well the pricing of the above services means that my organisation won’t readily adopt these new things, so for now at least continuing to leverage metadata rich lists & libraries will have to suffice! Here’s how I built a knowledge base in SharePoint Online…

IT Knowledge base image

Site features

  • Custom site theme/design
  • Mega-menu navigation
  • PnP modern search V3
  • Custom page templates
  • Site Pages library with additional metadata
  • Lookup value lists
  • Change log list

Web parts used

  • Image with colour block
  • Search box
  • Highlighted content
  • Image/ text
  • Page properties (KB articles)
  • Search results web part
  • Searh filters web part

Approach

I wanted to leverage the modern page authoring experience for creating pages, as there are several people adding content to the knowledge base (KB). So with that in mind the knowledge base is built around the Site Pages library, using the metadata applied to each knowledge base article to drive dynamic web parts throughout the site such as search, page properties and the highlighted content web part.

Within the KB, all KB articles get categorised by the type of technology, application and product they fall under. These work for my KB as I can fit KB articles within these headings. For example:

KB article: How to fix the sync connection in SharePoint 2010

TechnologyApplicationProduct
MicrosoftSharePoint ServerSharePoint 2010

Site Pages library

As mentioned above, the Site Pages library is the lynchpin to the entire knowledge base. Starting with the Pages library, I created columns to capture additional metadata about each KB article. Here are the columns I created:

Technology: lookup column, values held in custom list
Application: lookup column, values held in custom list
Product: lookup column, values held in custom list
Knowledge Type: choice column
Topic: Managed Metadata column
Contact: Person or Group

Technology, Application & Product are what drive each view within the Site Pages library. I have created a view for each Technology and Application, which are used for web parts embedded within the relevant pages (for example: Microsoft).

Product is used as a way to formalise the type of KB articles that are created (for example: Procedure), with Topic effectively being a way to tag KB articles with a wider variety of terms to aid searching and filtering.

Custom site theme/ design

I originally provisioned the site based on the news, resources, actions template in the SharePoint look book. From here I created a simple custom site theme following the excellent blog post how to configure and apply a custom theme in SharePoint Online by Greg Zelfond.

The only thing I did different is I used a different website to generate my theme which you can use here. This theme generator site allows you to access more of the colours that are used when creating a theme to potentially create a multi-coloured theme. For more information of this check out another great post by Laura Kokkarinen here.

Use a theme generator to create a custom theme for your SharePoint Online site.

Homepage

The homepage of the knowledge base is broken down into three key areas: search, recently added and the browse area.

Search: Search web part as part of the PnP modern search solution V3. Connected to a custom search results page (more information below).

Recently added: Highlighted content web part that only shows pages from this site, filtered by recently added earlier this year.

Browse: Three column section consisting of images, text and button web parts. I used the images from the look book template to get the correct sizing for the images above. When updating the images I noticed they didn’t update immediately which I wrote about how to fix here.


The navigation for the KB has been created using the mega menu option within the Change the look > Navigation options. The links have all been created manually for each section, with each link going to either a dedicated page or a view created from the Site Pages library.

Mega menu navigation in the IT KB.

Search web part

The search for the knowledge base is all based on web parts from the PnP modern search solution V3. From the homepage there is a search web part. Before configuring the search web part on the homepage you will need to create and configure the search results page and web part as it is required as a data source. I followed the guidance from the PnP modern search solution documentation to configure the search web part with the following properties:

The search web part configuration on the knowledge base homepage.

Search results

The search results is a dedicated page created within the knowledge base that includes the search box, search results and search filters web parts. The search box web part is configured in exactly the same way as on the homepage and just serves as a consistent way to see your search results and search again if required.

The search results web part has been added to a separate, one-third left section underneath the search box web part shared with the search filters web part. The search results web part has the following settings:

Connect to source: Page environment
Page environment’s properties: Search
Search: Search query
Use a default search query: No
Query template: {searchTerms} Path:{Site.URL} FileType=aspx
Result source identifier: No
Sort order: Created, size
Sortable properties: None
Connect to a search refiners web part: On
Use refiners from this component: Filter
Connect to search verticals: Off
Enable query rules: On
Include personal OneDrive results: Off
Selected properties: {searchTerms} Path:{Site.URL} FileType=aspx
Refinement filters: None
Show paging: On
Number of items per page: 30
Number of pages: 4
Hide navigation: No
Hide navigation if disabled: Yes
Results layout: Simple list

Search filter web part

The search filter web part has been added to the search results page with no additional configuration changes made. Don’t forget (like I did), to get the search filter web part to start to work with your search results, you need to turn it on within the search results web part – under connect to a search refiners web part!


Page templates

I’ve used page templates within the knowledge base to standardise the layout of each KB article. At the time of writing there are only two templates to choose from: an application template or new KB article.

Example KB article page template

The KB article page template includes a page properties web part that shows the Knowledge Type, Contact and Topic.

The layout of each KB article page template is as follows:
One-third right section: Text web part (left), Page properties web part (right)
One column section: Two text web parts
One column section: Two text web parts

How to create a page template

  • Create or open the page you want to use as your template
  • Press the down arrow next to the save button > Save as template

Page templates will now appear under saved on this site when creating a new page. Templates are also saved in a “Templates” folder within the Site Pages library.

Create page templates to standardise how knowledge is created.

More information on how to manage and delete templates can be found here.

Issues & next steps

Dependant drop-down lists, Power Apps and the Site Pages library

One area I would like to improve on is including the ability to have dependant drop-downs for Technology, Application and Product when applying metadata to KB articles. When creating the KB, I did work on two ways to achieve this- but they both fell short in the end.

My first attempt was to customise the Site Pages library new and edit forms using Power Apps. I used this article by Microsoft on how to create dependent drop-down lists in a canvas apps as a starting point, but had to make some changes to account for the additional third level of drop-down. Although I got this working within the context of PowerApps, I had to abandon this method as creating new pages in the Site Pages library via Power Apps is not supported. My experience was that once I customised the form in Power Apps, it pretty much broke the Site Pages library. I was unable to create new pages and it would default to an old style wiki page and not let me create modern site pages.

Custom forms for document libraries only supports editing custom metadata. Editing or managing file(s) is not supported.

https://docs.microsoft.com/en-us/connectors/sharepointonline/

After this failed, I also tried an older way of doing this by using JQuery and SPServices as described here.

Initially I got this to work too, but it was also a pretty poor solution when working with modern pages as the only way to actually get to the dependent drop-downs was by pressing “Edit all” which took you to the classic version of the edit properties page.

Aside from this, you also have to jump through several hoops to add in the old content editor web part, which are too numerous to describe in this post but have linked to one of them.

There was also a recent change to how classic forms work with modern lists that stopped this method working all together. Although this seems to be resolved, my understanding is you have to set your list to run in the classic experience in order to get this method to work – so I’ve scrapped this too!

I currently have no solution for dependant drop-downs, but am open for suggestions that are low code or relatively easy to implement. Feedback so far from users is that they aren’t all that bothered about it as the process to apply metadata is easy.

Images not updating when refreshing

As I was in the process of updating the KB homepage I noticed that when replacing some of the images or other assets that make up the page, they weren’t visibly updating after a forced browser refresh. I wrote a separate post called how to force images to update in SharePoint Online which details how to resolve this.

Updating the modern search solution

When I began building the KB I deployed what is now version 3 of the modern search solution. Since then the PnP team have created PnP Modern Search V4, I’ve personally decided not to update my search solution as at the time of writing V4 doesn’t support suggested keywords which is a part of my solution.


How to provision and deploy the PnP SharePoint Starter Kit part two

Update: The SharePoint Starter Kit is now a solution that’s available to apply from the SharePoint Online Provisioning Service:
https://provisioning.sharepointpnp.com/

This is second part of my two-part series on how to provision and deploy the SharePoint starter kit into your SharePoint tenant. You can read part one below:

How to provision and deploy the SharePoint Starter Kit part one

At this point all the pre-requirement steps should be completed, our Office 365 tenant should have an app catalog site, a dev site collection and a custom user profile service property.

Download the SharePoint Stater Kit

In order to deploy the SharePoint Starter Kit to your tenant you will need to clone or download a copy of the repository. I downloaded a copy of the repository and followed the steps below:

Downloading the SharePoint Starter Kit

Deploy the SharePoint Starter Kit

Now for the fun part…deploying the SharePoint Starter Kit to your tenant! Before you begin, make sure you have run the following cmdlet to connect to your tenant:

Connect-PnPOnline https://contosodemosk.sharepoint.com

  • Change the path in PowerShell to the location where your SP Starter Kit provisioning folder is located

Set-Location -Path C:\sp-starter-kit-master\provisioning

  • Finally, in PowerShell run the following command

Apply-PnPTenantTemplate -Path starterkit.pnp

Deploying the SharePoint Starter Kit in PowerShell

Once the SharePoint Starter Kit has concluded it will provision 3 site collections as well as other tenant level settings like themes, site designs and taxonomy term sets. You will be able to access all the site collections and web parts deployed through the starter kit in your tenant either through the new SharePoint admin center or through the SharePoint app in Office 365.

References

https://github.com/SharePoint/sp-starter-kitSharePoint Starter Kit repository from GitHub

https://docs.microsoft.com/en-us/sharepoint/dev/spfx/set-up-your-development-environmentsteps to install the required developer tools from Microsoft

https://docs.microsoft.com/en-us/powershell/sharepoint/sharepoint-pnp/sharepoint-pnp-cmdlets?view=sharepoint-pssteps to install PnP PowerShell from Microsoft

https://docs.microsoft.com/en-us/sharepoint/dev/spfx/set-up-your-developer-tenant – setting up your Office 365 tenant to build and deploy client-side web parts using the SharePoint Framework from Microsoft

https://github.com/SharePoint/sp-starter-kit/blob/master/documentation/tenant-settings.mdcreating the new user profile property/ requesting API key to Alpha Vantage from GitHub

https://github.com/SharePoint/sp-starter-kit/tree/master/provisioningPowerShell commands and minimal path to success from GitHub

https://github.com/SharePoint/sp-starter-kit/blob/master/documentation/common-provision-results.mdPre-requirement steps added from general cascading errors from GitHub

How to provision and deploy the PnP SharePoint Starter Kit part one

Update: The SharePoint Starter Kit is now a solution that’s available to apply from the SharePoint Online Provisioning Service:
https://provisioning.sharepointpnp.com/

This is the first of a two-part series on how to provision and deploy the SharePoint starter kit into your SharePoint tenant. Part-two of this series can be found below:

How to provision and deploy the PnP SharePoint Starter Kit part two

Although there is plenty of great documentation out there already (I’ll also reference and link to said documentation throughout) I wanted to provide a comprehensive step-by-step guide for those with little or no experience of SharePoint Framework, PnP Powershell or anything else with the least amount of steps required to get the SharePoint starter kit up and running in a Office 365 tenant.

I followed the all of the steps below to get the SP starter kit working in my environment:

Pre- requirements

Make sure that all of the pre-requirements below have been met to ensure that the SharePoint Starter Kit will work in your tenant.

  • Ensure you are connecting to the tenant account using an administrator account
  • Your tenant must be set to targeted release for all users, and you must wait at least 24 hours after setting targeted release before deploying SP Starter Kit
  • Check that the account being used has been added as a term store administrator

LINK: setting up the targeted release option in Office 365

Install developer tools and setup SharePoint Framework dev environment

Before you can get started with the starter kit, you need a SharePoint Framework development environment, this consists of:

  • Install NodeJS LTS version 8
  • Install a code editor – I used Visual Studio Code
  • Install Yeoman and gulp – I installed these using the command prompt
  • Install Yeoman SharePoint generator – as above
  • Install PnP PowerShell – you need to be running Windows 10 or have PowerShellGet installed to run these commands. I’m running Windows 10, so I just ran the Install-Module SharePointPnPPowerShellOnline in PowerShell as an administrator
  • Run Update-Module SharePointPnPPowerShell* to make sure its the latest version

LINK: setting up the SharePoint Framework development environment
LINK: Installing PnP PowerShell
LINK: updating the PnP PowerShell version

Office 365 tenant configuration

Once you have been through the pre-requirement steps, configured your environment for SharePoint Framework development and you are using the latest version of PnP PowerShell, you now can move onto the tenant configuration steps:

Create an app catalog site

  • In the SP admin center, on the left sidebar select the apps menu item, then select app catalog
  • Press OK to create a new app catalog site
Select app catalog from the apps menu option
  • Enter the following details
    • Title: app catalog
    • Web Site Address suffix: enter your preferred suffix for the app catalog; for example: apps
    • Administrator: enter your username, and then select the resolve button to resolve the username
  • Press OK

Create a new developer site collection

In the SharePoint admin center, in the ribbon select New > Private Site Collection. Enter the following details:

  • Title: Enter a title for your developer site collection; for example: Developer Site
  • Web Site Address suffix: Enter a suffix for your developer site collection; for example: dev
  • Template Selection: Select Developer Site as the site collection template
  • Administrator: Enter your username, and then select the resolve button to resolve the username
  • Press OK

Remember the SharePoint Workbench URL

SharePoint Workbench enables you to be able to test and preview web parts without fully deploying them into your SharePoint environment. You can access the SharePoint Workbench by using the following URL:

https://your-sharepoint-site/_layouts/workbench.aspx

LINK: Office 365 tenant configuration steps

Create a custom property in the User Profile Service

In the SP admin center, on the left sidebar select the user profiles menu item, then under People, select Manage User Properties

Select manage User Properties from the User Profiles menu option
  • Select New Property from the ribbon options
Select New Property

Configure the new property with the following settings:

  • Name: PnP-CollabFooter-MyLinks
  • Display name: PnP-CollabFooter-MyLinks
  • Type: string (Single Value)
  • Length: 3600 (which is the maximum allowed)
  • Policy Setting: Optional
  • Allow users to edit values for this property: Checked
  • Leave all the other properties with their default value

LINK: preparing your tenant for the PnP SharePoint Starter Kit

Request a custom API key to Alpha Vantage

The API key from Alpha Vantage uses the live stocks service in the Stock Information Web Part. This is not a mandatory step, but I’ve included it for completeness for the starter kit:

In part two I’ll cover downloading the SharePoint Starter Kit, deploying it to your tenant and testing everything has worked.