Skip to main content

​
Introduction

This guide shows you how to create an internal knowledge base on Mintlify. You’ll set up a navigation structure, migrate content, configure authentication, and establish a maintenance process. This guide assumes you are migrating content from an existing knowledge base to Mintlify. If you are creating a knowledge base with entirely new content, you can follow similar steps but skip the audit and migration steps. If you haven’t created a Mintlify project yet, see the Quickstart to deploy your site.

​
Prerequisites

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

​
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 that needs to be preserved 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.

​
Design the navigation structure

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 how your knowledge base is organized. 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.
1

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.
2

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...
3

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).
4

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.
5

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.

​
Optimize discoverability

​
Configure AI assistant

The assistant is automatically enabled for Pro and Custom plans. You can customize the assistant from your dashboard.
  • Search sites: Select additional sites other than your knowledge base that the assistant can search when responding to questions.
  • Set sample questions: Set default questions that appear when someone opens the assistant panel. If people have frequent questions like “how do I submit an expense report” or “what is the company’s vacation policy”, add them here to save people time.

​
Slack integration

If your team uses Slack, you can add the Slack app to your workspace. This lets your team query your knowledge base without leaving Slack.

​
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.
1

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.
2

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?
3

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?
4

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:
  1. Announce the knowledge base to your team.
  2. Monitor usage and search patterns in your analytics.
  3. Encourage contributions when people find gaps.
  4. Review and update content regularly.
The most successful knowledge bases evolve based on how teams actually use them.