Setting Up a Knowledge Base

How to get there: Go to Settings in the sidebar → Boards (separate page) → create a new board with the Knowledge Base type.

Learn how to create and manage a knowledge base in ProductLift to provide self-service documentation, help articles, and guides for your users.

What is a Knowledge Base?

A knowledge base is a structured collection of articles organized into sections that help your users find answers to common questions, learn how to use your product, and troubleshoot issues independently.

ProductLift's knowledge base features:

  • Hierarchical organization with sections and subsections
  • Rich text articles with images and formatting
  • Search functionality for users
  • Customizable section icons and colors
  • Markdown sync for developer-friendly content management
  • SEO optimization with meta tags and sitemaps

Creating a Knowledge Base Board

Step 1: Access Board Settings

  1. Go to Settings in your admin dashboard
  2. Navigate to Boards & Statuses
  3. Click "Add Board" button

Step 2: Configure the Board

Required Fields:

  • Name: The display name for your knowledge base (e.g., "Help Center", "Documentation", "Guides")
  • Type: Select "Knowledge Base"

Optional Settings:

  • Icon: Choose an icon to display next to the board name
  • Visibility: Control who can see the knowledge base

[Screenshot: Board creation form with Knowledge Base type selected]

Step 3: Save and Position

After creating the board:

  1. Drag the board to reorder it in your navigation
  2. The knowledge base board appears in your portal's main navigation

Understanding Sections

Sections are the organizational units of your knowledge base. Think of them as folders or categories that group related articles together.

Section Hierarchy

ProductLift supports nested sections:

Help Center (board)
├── Getting Started (section)
│   ├── Quick Start Guide (article)
│   └── Installation (article)
├── Features (section)
│   ├── Dashboard (subsection)
│   │   ├── Overview (article)
│   │   └── Customization (article)
│   └── Reports (subsection)
│       └── Creating Reports (article)
└── Troubleshooting (section)
    └── Common Issues (article)

Creating Sections

From the Knowledge Base view:

  1. Navigate to your Knowledge Base board
  2. Click "Add Section" or the "+" button
  3. Enter section details:
    • Title: Section name
    • Icon: Optional icon (Bootstrap icons)
    • Color: Optional color for the icon
    • Description: Optional description text
  4. Click Save

Creating Subsections:

  1. Navigate to the parent section
  2. Click "Add Subsection" within that section
  3. Configure the subsection details
  4. The subsection appears nested under the parent

Section Settings

Each section can be customized:

Setting Description
Title Display name for the section
Icon Bootstrap icon name (e.g., "book", "star", "gear")
Color Hex color for the icon (e.g., "#60a5fa")
Description Optional text shown below the section title
Hidden from Users When enabled, only admins can see the section

Reordering Sections

Drag and drop sections to reorder them within the knowledge base. The order affects how sections appear to users.

Creating Articles

Articles are the content pages within your knowledge base sections.

Creating an Article

  1. Navigate to the section where you want the article
  2. Click "Add Article" or "New Post"
  3. Enter article details:
    • Title: Article headline
    • Content: Rich text content with formatting
  4. Click Save or Publish

Article Editor

The article editor supports:

  • Headers: H1-H6 heading levels
  • Text formatting: Bold, italic, underline, strikethrough
  • Lists: Ordered and unordered lists
  • Links: Internal and external links
  • Images: Upload or embed images
  • Code blocks: Syntax-highlighted code snippets
  • Tables: Data tables
  • Blockquotes: Quoted text

Article Visibility

Articles have two states:

  • Published: Visible to all users
  • Unpublished: Only visible to admins (draft state)

Use unpublished state for work-in-progress articles before they're ready for users.

Markdown Sync

For teams that prefer managing documentation as code, ProductLift supports syncing knowledge base content from markdown files.

How Markdown Sync Works

  1. Create markdown files organized in folders
  2. ZIP the folder structure
  3. Upload to ProductLift
  4. Preview and confirm changes
  5. Content syncs to your knowledge base

Folder Structure

docs/
├── getting-started/
│   ├── _index.md          # Section metadata
│   ├── quick-start.md     # Article
│   └── installation.md    # Article
├── features/
│   ├── _index.md
│   └── dashboard.md
└── images/
    └── screenshot.png     # Shared images

Section Index Files (_index.md)

Each folder needs an _index.md file with section metadata:

---
title: Getting Started
icon: rocket
color: "#60a5fa"
---

Optional description text for the section.

Article Files

Articles are standard markdown files. The first H1 becomes the title:

# Quick Start Guide

Welcome to our product! This guide will help you get started.

## Step 1: Create an Account

First, sign up at our website...

## Step 2: Configure Settings

Navigate to Settings and...

Syncing Content

  1. Go to your Knowledge Base board
  2. Click "Sync Markdown" or access via settings
  3. Upload your ZIP file
  4. Preview the changes:
    • New: Articles and sections to be created
    • Updated: Existing content that will change
    • Deleted: Content that exists in ProductLift but not in the ZIP
  5. Confirm deletions if needed
  6. Click Execute to sync

Exporting Content

Export your knowledge base as markdown:

  1. Go to your Knowledge Base board
  2. Click "Export"
  3. Download the ZIP file
  4. Edit files locally
  5. Re-upload to sync changes

Best Practices for Markdown Sync

Unique Filenames:
Each markdown file must have a unique filename across all folders. The system uses filenames to track synced articles.

# Good
docs/getting-started/getting-started-overview.md
docs/advanced/advanced-overview.md

# Bad - will cause conflicts
docs/getting-started/overview.md
docs/advanced/overview.md

Images:
Place images in an images/ folder and use relative paths:

![Screenshot](../images/screenshot.png)

Images are automatically uploaded to cloud storage during sync.

Organizing Your Knowledge Base

Planning Structure

Before creating content, plan your structure:

  1. Identify topics: What do users need to know?
  2. Group related content: Which articles belong together?
  3. Create hierarchy: What should be top-level vs. nested?
  4. Plan for growth: Leave room for future content

Common Structures

By User Journey:

Getting Started
├── Quick Start
├── Installation
└── First Steps
Using the Product
├── Core Features
├── Advanced Features
└── Integrations
Troubleshooting
└── Common Issues

By Feature Area:

Dashboard
├── Overview
├── Widgets
└── Customization
Reports
├── Creating Reports
├── Sharing
└── Scheduling
Account
├── Settings
├── Billing
└── Team Management

Section Visibility

Use the "Hidden from Users" setting to:

  • Create internal-only documentation
  • Stage content before launch
  • Keep admin guides separate

Best Practices

Content Quality

  • Clear titles: Use descriptive, searchable titles
  • Consistent formatting: Follow a style guide
  • Visual aids: Include screenshots and diagrams
  • Keep current: Update articles when features change

Organization

  • Logical grouping: Put related content together
  • Shallow nesting: Avoid more than 3 levels deep
  • Clear navigation: Users should find content easily
  • Regular review: Audit and update content periodically

SEO

Your knowledge base articles are indexed by search engines. Optimize by:

  • Using descriptive titles
  • Writing clear excerpts/descriptions
  • Including relevant keywords naturally
  • Enabling indexing in portal settings

Troubleshooting

Issue: Section not appearing

Solution:

  • Check if the section is marked "Hidden from Users"
  • Verify the section has at least one published article
  • Clear your browser cache

Issue: Markdown sync errors

Solution:

  • Ensure all filenames are unique
  • Check that _index.md exists in each folder
  • Verify the ZIP structure is correct
  • Review the preview for errors before executing

Issue: Images not displaying

Solution:

  • Use relative paths (../images/file.png)
  • Ensure images are in the ZIP file
  • Check image file extensions are supported