Create an internal knowledge base

An internal knowledge base gives your team one place to find answers and one place to record them. When knowledge is spread across chat threads, wikis, shared drives and people’s heads, a search returns the wrong answer or none at all. A knowledge base fixes that by making one source the source of truth.

This guide covers building one with Reed: migrating what you have, structuring it, keeping it private, and making sure it is still right a year from now.

Is Reed the right tool for this?

Be clear about the trade before you start. Reed is a compiler: it turns a directory of MDX files and one docs.json into a static site. That shapes what a knowledge base on Reed is like.

What you get:

• Pages in git. Every change is a commit, every edit is reviewable, and nothing is lost when someone overwrites a page.
• Fast search with nothing to run. Search is built into the site and runs in the reader’s browser. There is no search server to operate.
• A site that outlives the tool. The output is static files you host anywhere.
• Plain-text copies for AI tools. Every build writes llms.txt and a markdown mirror of each page, so your team’s own AI tooling can read the knowledge base without scraping it. See llms.txt.

What you do not get:

• Access control. Reed has no login, no SSO, no user groups and no per-page permissions. “Internal” is something you enforce in front of the site, not inside it. The next sections show how.
• A web editor. Contributors edit files in git. There is no in-browser editor from Reed.
• An assistant or chat integration. No question-answering widget on the page and no bot in your chat tool.
• Usage reporting of its own. Page views come from an analytics provider you configure.

If most of your contributors will never open a pull request, weigh that honestly. A knowledge base nobody updates is worse than none. If your team already lives in git, the trade is a good one.

Prerequisites

• Reed installed and a project that builds. See the Quickstart.
• A git repository your contributors can reach.
• A place to host static files that you can put behind authentication: a Cloudflare Pages project with Cloudflare Access, a bucket behind your VPN, or an nginx server you control.

Migrate existing content

If you are starting from scratch, skip to designing the navigation.

Audit what you have

Catalog your current knowledge base before you move it. The catalog sizes the migration, shapes the new structure, exposes gaps, and gives you a checklist to confirm everything arrived.

• Number of articles. Sets the effort estimate and lets you track completeness.
• Topics. Tells you what the navigation has to hold.
• Current organization. Shows whether the existing structure is worth keeping.
• Content types. Text, PDFs, videos and embeds each migrate differently.
• Metadata. Dates, authors and tags you need to preserve somewhere.
• Audiences. Who is allowed to read what. This decides how many sites you build, as covered below.

Export your content

Most wiki and knowledge-base tools export in standard formats.

• Markdown is the simplest path, and the one to choose if it is offered. Reed pages are MDX, and most Markdown is valid MDX.
• HTML works when Markdown is not available. You will convert it before it becomes a page.
• JSON or CSV preserves structured metadata, such as owners and review dates, that you may want to carry into the new pages or into a separate ownership list.

Reed has no importer for wiki platforms. reed import --from fern is the only conversion path it ships, so a migration from anything else is an export, a conversion and a cleanup.

Design the navigation structure

Navigation decides how people find things. You can recreate your existing structure or use the migration to fix it.

Ask whether the current structure actually works. If people navigate your old wiki only through search, its hierarchy is not helping anyone, and you are free to redraw it.

On Reed the structure lives in the navigation field of docs.json, as tabs holding groups holding pages:

json

{
  "navigation": {
    "tabs": [
      {
        "label": "Handbook",
        "groups": [
          {
            "label": "Finance",
            "pages": [
              "finance",
              "finance/budgeting-process",
              "finance/expense-reports",
              "finance/cost-allocation"
            ]
          },
          {
            "label": "People",
            "pages": ["people", "people/onboarding", "people/benefits", "people/time-off"]
          },
          {
            "label": "Engineering",
            "pages": [
              "engineering",
              "engineering/dev-setup",
              "engineering/deployment",
              "engineering/code-standards"
            ]
          }
        ]
      }
    ]
  }
}

A tab holds groups, a group holds pages, and groups can nest up to five levels. Keep it shallower than that. How to structure documentation navigation covers depth, naming and testing the structure with real readers.

Keep it internal

Reed does nothing to restrict who can read the site. Everything in the build output is public to anyone who can reach the URL. You make it internal by putting the whole output behind an access layer you already trust:

• An identity-aware proxy such as Cloudflare Access in front of a Cloudflare Pages project, which checks your identity provider before serving any file.
• A private network. Serve the files from a host that is only reachable over your VPN or office network.
• Web-server authentication, such as nginx auth_basic or an auth module in front of the directory. This is the bluntest option and fine for a small team.

Protect the whole directory, not just the HTML pages. The build also contains llms.txt, a .md mirror of every page, and the search index, and each of them carries your content. A gate that covers only *.html leaks the rest.

When different teams need different content

Reed has no groups and cannot hide a page from some readers and show it to others. If a section must be restricted to one team, build it as a separate Reed project and put it behind its own access policy, at its own URL or base. Two builds cost you a second navigation and no search across both. Before you pay that, check whether the restriction is real. Most knowledge-base content is fine for everyone inside the company.

Migrate your content

Move the exported files into a layout that matches your navigation, convert what needs converting, and fix the links.

Organize the files

A page’s id comes from its path under content/, and that id is what navigation lists. content/finance/expense-reports.mdx is the page finance/expense-reports. A file named index.mdx inside a folder takes the folder’s id, so content/finance/index.mdx is the page finance — a natural overview page for the section.

• docs.json
• Directorycontent/!

  • Directoryfinance/!

    • index.mdx page id: finance
    • budgeting-process.mdx
    • expense-reports.mdx
    • cost-allocation.mdx
  • Directorypeople/

    • index.mdx
    • onboarding.mdx
    • benefits.mdx
    • time-off.mdx
  • Directoryengineering/

    • index.mdx
    • dev-setup.mdx
    • deployment.mdx
    • code-standards.mdx

Every file must be listed in navigation. A page left out fails reed check with content-page-not-in-navigation, so you find the stragglers before anyone else does.

Add frontmatter to each page

Every page needs a title and a description. The title becomes the page heading, so do not repeat it as a # heading in the body; start at ##.

mdx

---
title: Submit an expense report
description: How to file an expense report, attach receipts and track reimbursement.
---

## Before you start

See Pages for the details.

Fix internal links

Old wiki links will not survive the move. Rewrite them as root-relative paths built from the page id. If your site sets a base, include it yourself: on a site mounted at /handbook, a link to onboarding is written [Onboarding](/handbook/people/onboarding). Reed does not rewrite links, so a link missing the base compiles cleanly and 404s. How to link documentation pages effectively covers the rule and how to check links mechanically.

Convert HTML and other formats

If you exported HTML, convert it to Markdown. Pandoc handles most of it from the command line:

sh

pandoc expense-reports.html -f html -t gfm -o content/finance/expense-reports.mdx

Then read every converted page. Conversions leave behind stray markup, broken tables and headings at the wrong level, and some leftover HTML is not valid MDX. Convert in batches and run reed check and reed build after each one, so a broken page is found while you still remember where it came from.

Decide what to do with PDFs and videos

• Videos. Reed has no video component. Host the video on a platform built for it, link to it, and put the essential information in the page text too. See How to use images, screenshots and videos.
• PDFs. Reed does not publish arbitrary files alongside your pages. Host PDFs somewhere your team can reach and link to them by absolute URL — or, better, convert the ones people actually read into pages, so they are searchable.
• Images go next to the page that uses them, referenced with a relative path. The media guide explains why.

Enable team contributions

A knowledge base stays accurate only when the people who notice a mistake can fix it. Reed’s contribution model is git, so make git as easy as it can be.

• Edit in the browser on your git host. Most git hosts let anyone with access edit a file and open a pull request without installing anything. For a one-paragraph fix, that is the lowest-friction path.
• Edit locally with a preview. Contributors who make larger changes run reed dev for a live preview while they edit.
• Review every change. Pull requests give each change an author, a reviewer and a history. Run reed check on each one in CI so broken navigation never merges. See Git workflows for documentation.

Capture knowledge from chat

Much of what a team knows is first written in a chat thread and never makes it any further. Reed has no chat integration, so capture has to be a habit. When a thread settles a technical decision, a fix or a process, whoever resolved it opens an issue or a pull request with the answer while the context is fresh. An AI coding assistant working in the docs repository can do the drafting if you paste in the thread. A person still reviews the result before it merges.

Establish maintenance workflows

Knowledge bases decay fast. Build the maintenance in from day one.

Assign an owner to every section

An owner does not write every page. They review the section regularly, flag what is out of date, approve new pages, and respond when someone reports an error. Writing owners into a CODEOWNERS file makes your git host request their review automatically.

Set review cycles

Content goes stale at different rates. A reasonable starting schedule:

• Critical content, such as security and incident procedures: every 30 days.
• Standard content: every 90 days.
• Evergreen content: once a year.

When reviewing, check that links still work, systems and processes have not changed, examples are current, and nothing new belongs on the page. Git history tells you when each page last changed. How to maintain documentation over time shows how to surface stale pages from it.

Write contribution guidelines

Make it easy for anyone to help. Cover:

• Format: the templates and structure pages should follow. Content templates is a starting point.
• Process: how to propose a change and open a pull request.
• Review: who reviews, and how quickly.
• Scope: what belongs in the knowledge base and what does not.

Watch how it is used

Configure an analytics provider for page views. For an internal site, a self-hosted Plausible, Umami or Matomo instance keeps the data inside your infrastructure. Review monthly or quarterly:

• Most-viewed pages deserve the most care.
• Pages with no views need better discoverability or deletion.
• High bounce rates can mean the answer was found at once, or that the page failed. Ask the people who use it.

Search runs in the reader’s browser and records nothing, so there is no report of what people searched for. Questions asked in chat that the knowledge base already answers are the next best signal.

Next steps

Once the knowledge base is live behind your access layer:

1. Announce it, and link to it from the places people currently ask questions.
2. Watch page views and the questions people still ask in chat.
3. Encourage every person who finds a gap to open a pull request that fills it.
4. Keep the review cycles you set. The knowledge bases that last are the ones that change with how the team actually works.