Create a knowledge base

An internal knowledge base helps your team find answers and maintain a source of truth. If your team has information spread across different channels and platforms, people might find inaccurate or no information when they search for answers. A centralized knowledge base solves this by putting answers where everyone can find them and giving your team a specific place to record shared knowledge. Mintlify provides the infrastructure for knowledge bases that your entire team can contribute to.

AI-powered search: The assistant answers questions using your knowledge base content, so people find answers without knowing exactly where to look.
Slack integration: Add the assistant to Slack so your team can ask questions without leaving their workflow.
Low-barrier contributions: The web editor and agent let anyone on your team update content without learning Git or Markdown.
Authentication built-in: Control access with SSO or OAuth, and use personalization to show different content to different groups.

Prerequisites

If you haven’t created a Mintlify project yet, see the Quickstart to deploy your site.

An authentication system (SSO or OAuth provider like Okta or Azure AD)
Control over your domain for hosting
Admin access to your Mintlify organization

Migrate existing content

If you’re creating a knowledge base from scratch, skip to Design the navigation structure.

Audit existing content

Catalog the content you currently have in your existing knowledge base. This helps you understand what content you need to migrate, plan how to organize it in your new knowledge base, identify any gaps in your content, and confirm that you moved all of your content to your new knowledge base.

Total number of articles: Helps estimate migration effort and track completeness.
Topics and content: Informs your navigation structure and content organization.
Current organization: See how your content is currently organized and whether it matches your desired structure.
Content types: Determine any content conversion requirements for text, PDFs, videos, and embedded content.
Metadata: Identify any metadata to preserve like dates, authors, and tags.
Access requirements: Determine the best authentication approach for your knowledge base.

Export your existing content

Most knowledge base platforms support exporting content in standard formats. The format you choose depends on your current platform and your priorities.

Export to Markdown for the simplest migration to Mintlify. (recommended)
Export to HTML if Markdown isn’t available. You must convert your content to Markdown later.
Export to JSON or CSV if you have structured metadata to preserve.

Your navigation structure determines how people find content in your knowledge base. You can recreate your existing structure or redesign it to better match how your team thinks about the content.

Migrating is a good time to improve your structure. Consider whether your current organization actually works for your team, or if you can reorganize to make information easier to find.

Your docs.json file defines the navigation structure of your knowledge base. Create this file at the root of your project repository.

{
  "navigation": {
    "groups": [
      {
        "group": "Finance",
        "pages": [
            "finance/overview",
            "finance/budgeting-process",
            "finance/expense-reports",
            "finance/cost-allocation"
        ]
      },
      {
        "group": "HR",
        "pages": [
            "hr/overview",
            "hr/onboarding",
            "hr/benefits",
            "hr/time-off-policy"
        ]
      },
      {
        "group": "Engineering",
        "pages": [
          "engineering/overview",
          "engineering/dev-setup",
          "engineering/deployment",
          "engineering/code-standards"
        ]
      }
    ]
  }
}

See Navigation for more information on how to structure your knowledge base.

Set up authentication

Determine who needs access to what content in your knowledge base. If everyone should have access to the entire knowledge base, set up only authentication. If you need to restrict access to certain content to specific users or groups, set up authentication and personalization.

Migrate your content

Move your exported content into a folder structure that matches the navigation structure you designed. Convert content to Markdown if needed, add any missing frontmatter, and set up internal links.

Organize files

Create folders that match your docs.json structure. For example, if your docs.json has a Finance group, create a finance/ folder:

your-project/
├── docs.json
├── finance/
│   ├── overview.mdx
│   ├── budgeting-process.mdx
│   ├── expense-reports.mdx
│   └── cost-allocation.mdx
├── hr/
│   ├── overview.mdx
│   ├── onboarding.mdx
│   ├── benefits.mdx
│   └── time-off-policy.mdx
└── engineering/
    ├── overview.mdx
    ├── dev-setup.mdx
    ├── deployment.mdx
    └── code-standards.mdx

Place each article in its corresponding folder. The file path must match the path in your docs.json. For example, if docs.json references "finance/expense-reports", the file should be finance/expense-reports.mdx in your project repository.

Add frontmatter to each article

Every .mdx file needs frontmatter at the top with metadata. Every page requires a title and description. See Pages for more information on page metadata.

---
title: "Expense Report Process"
description: "How to submit and track expense reports"
---

Your content here...

Set up internal links

Link between pages using paths from your project root.

See [Onboarding Guide](/hr/onboarding) for new employee setup.

For questions, contact [HR Benefits Team](/hr/benefits#common-questions).

Convert HTML and other formats to Markdown

If you exported your content as HTML, convert it to Markdown. Some tools that can help include:

Pandoc: Command-line tool that converts between many formats.
CloudConvert: Online converter supporting HTML, DOCX, PDF, and more.
VS Code extensions: Search for “HTML to Markdown” in extensions.

Handle multiple content formats

If you have PDFs, videos, or other media, decide how to include them in your knowledge base.

Embed videos: Embed videos or link to hosted videos.
Link to PDFs: Add PDFs to your project repository and link to them from relevant pages.
Convert PDFs to Markdown: If you want the content of a PDF to be a page, convert PDFs to Markdown.

Set up the assistant

The assistant is automatically enabled for Pro and Custom plans. The assistant lets your team ask questions and get answers with cited sources from your knowledge base. Configure the assistant from your dashboard:

Sample questions: Add common questions like “how do I submit an expense report” or “what is the vacation policy” so people can get answers with one click.
Search sites: Include additional sites the assistant can search when answering questions.
Deflection email: Set a support email for questions the assistant can’t answer.

Add the assistant to Slack

The Slack bot lets your team ask the assistant questions without leaving Slack. Create a channel where the bot responds to every message or let people @mention the bot in any channel.

Enable team contributions

A knowledge base stays accurate when everyone can update it, not just the people who set it up. Mintlify provides three ways for team members to contribute quickly to your knowledge base.

Web editor

The web editor lets anyone create and edit pages in their browser. Contributors can:

Edit pages visually or in Markdown.
Drag and drop to reorganize navigation.
Upload images and media.
Create branches and pull requests for review.

This works well for subject matter experts who know the content but aren’t comfortable with code workflows.

Agent

The agent in your dashboard creates documentation updates from natural language prompts. Describe what you want to change, and the agent creates a pull request with the updates. For example, a team member could prompt “add a section to the expense policy page explaining how to submit receipts for meals over $50” and copy the existing expense policy page into the prompt. The agent would draft the content and open a PR for review.

Locally

Anyone with access to your knowledge base repository can work locally in their preferred editor and push changes to your repository.

Establish maintenance workflows

A knowledge base can decay quickly without maintenance. Set up systems to keep content up to date and help your team contribute to the knowledge base.

Assign content ownership

Designate an owner or small team for each section. They don’t have to write all the content, but they’re responsible for:

Reviewing content regularly.
Flagging outdated information.
Approving new pages in their section.
Responding when people report errors.

Set up review cycles and content verification

Content becomes stale over time. Establish a review schedule.

Critical content: Review every 30 days
Standard content: Review every 90 days
Evergreen content: Review yearly

When reviewing, check:

Are links still valid?
Have systems or processes changed?
Are examples current?
Is there new information that should be added?

Create contribution guidelines

Make it easy for anyone to improve the knowledge base. Your guidelines should cover:

Format: Do you have specific templates or format requirements?
Process: How should someone propose and submit changes?
Review: Who reviews submissions? What’s the turnaround time?
Scope: What types of content are in scope?

Monitor usage metrics

Review how your team uses the knowledge base to prioritize content and identify areas for improvement. Set a regular cadence for reviewing usage metrics—monthly or quarterly are good intervals.

Which articles get the most views? Invest in keeping these accurate and easy to read.
Which articles get no views? Consider removing them or improving discoverability.
What’s the bounce rate? If people leave immediately, the content might not be helpful or navigation could be improved.

Next steps

Your knowledge base is ready to launch. After deploying:

Announce the knowledge base to your team.
Monitor usage and search patterns in your analytics.
Encourage contributions when people find gaps.
Review and update content regularly.

The most successful knowledge bases evolve based on how teams actually use them.

Overview

AI

API docs

Best practices

Git

Use cases

Create a knowledge base

Prerequisites

Migrate existing content

Audit existing content

Export your existing content

Design the navigation structure

Set up authentication

Migrate your content

Set up the assistant

Add the assistant to Slack

Enable team contributions

Web editor

Agent

Locally

Establish maintenance workflows

Next steps

Overview

AI

API docs

Best practices

Git

Use cases

​Prerequisites

​Migrate existing content

​Audit existing content

​Export your existing content

​Design the navigation structure

​Set up authentication

​Migrate your content

​Set up the assistant

​Add the assistant to Slack

​Enable team contributions

​Web editor

​Agent

​Locally

​Establish maintenance workflows

​Next steps

Prerequisites

Migrate existing content

Audit existing content

Export your existing content

Design the navigation structure

Set up authentication

Migrate your content

Set up the assistant

Add the assistant to Slack

Enable team contributions

Web editor

Agent

Locally

Establish maintenance workflows

Next steps