I Want a Beautiful Knowledge Base Like the Big Companies Have

I've always envied the knowledge bases of companies like Stripe, Cloudflare, and Notion — clean design, fast search, multilingual, looks great on mobile.

But surely that requires serious money, or a team of engineers?

I asked AI. The answer surprised me.

---

What I Tried Before Asking AI

My first instinct was Notion: free, pretty, easy to start. But Notion public pages have some real problems — slow load times, practically zero SEO, and brand customization is nearly impossible.

Then I looked at GitBook. The SaaS plan isn't cheap, and having my content locked on someone else's platform felt uncomfortable.

WordPress was a non-starter — plugins, database maintenance, CDN configuration. Exhausting just to think about.

---

What AI Recommended

I summarized my requirements and asked AI:

I need a knowledge base with: multilingual support, built-in search, SEO-friendly, free or nearly free, customizable branding, low maintenance cost.

AI gave me several directions:

Option	Pros	Cons
Notion	Easy to start	Poor branding, weak SEO, paid plan for custom domain
GitBook	Nice design	Expensive monthly fee, content not yours
Docusaurus	Feature-rich	Complex setup, React knowledge required
VitePress	Lightweight, fast, clean design	Requires basic Markdown knowledge
MkDocs	Python ecosystem	Few themes, feels more engineering-oriented

AI recommended VitePress — because it's the framework powering Vue's official documentation, the community is active, the default theme looks great without much tweaking, and deploying to Cloudflare Pages is completely free.

So I tried it.

---

What Is VitePress

VitePress is a static site generator built specifically for technical documentation and knowledge bases.

You write Markdown, it generates beautiful web pages. Navigation, sidebar, full-text search, dark mode, multilingual — all built in, no plugins needed.

Vue, Vite, and Vitest all use VitePress for their official docs. That experience you get when reading those docs — that's VitePress's default.

---

The Build Process

1. Initialize the Project

npm create vitepress@latest

Follow the interactive prompts, pick a name and choose the Default theme. About a minute to initialize.

Enter the directory and install:

cd my-knowledge-base
npm install
npm run docs:dev

Open http://localhost:5173 to see a live local preview.

---

2. Configure config.mts (The Most Important Step)

All settings live in docs/.vitepress/config.mts:

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'My Knowledge Base',
  description: 'Company Knowledge Base',
  outDir: '../public',

  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Product Docs', link: '/docs/intro' },
    ],
    sidebar: {
      '/docs/': [
        {
          text: 'Getting Started',
          items: [
            { text: 'Introduction', link: '/docs/intro' },
            { text: 'Installation', link: '/docs/install' },
          ],
        },
      ],
    },
    search: {
      provider: 'local',   // built-in search, no third-party service needed
    },
  },
})

Nav, sidebar, search — a few lines of config and you're done.

---

3. Multilingual Setup

To add multiple languages, use locales in the config:

export default defineConfig({
  locales: {
    root: {
      label: 'English',
      lang: 'en-US',
      themeConfig: {
        nav: [...],
        sidebar: {...},
      },
    },
    'zh-tw': {
      label: '繁體中文',
      lang: 'zh-TW',
      themeConfig: {
        nav: [...],
        sidebar: {...},
      },
    },
  },
})

Each locale has its own nav and sidebar. Articles go in the corresponding directory (docs/zh-tw/...).

---

4. Writing Content

Each article is a .md file, supporting standard Markdown plus VitePress extensions:

# Article Title

Body content, supports **bold**, `inline code`, tables, etc.

::: tip Note
This is a tip callout box
:::

::: warning Warning
This is a warning callout box
:::

Directory structure maps directly to URLs: docs/products/intro.md → /products/intro

---

5. Build and Deploy to Cloudflare Pages

npm run docs:build

Outputs static HTML/CSS/JS to the outDir directory.

Deploy with Wrangler CLI:

npx wrangler pages deploy ./public --project-name my-knowledge-base

Or connect your GitHub repo to Cloudflare Pages — every push triggers an automatic build and deploy without running any commands yourself.

---

What the End Result Looks Like

• Clear categorized left sidebar
• Auto-generated right-side page outline (pulled from headings)
• Top search bar with full-text indexing
• Dark / light mode toggle
• Fully responsive on mobile
• Language switcher
• "Last updated" timestamp on every article

The design quality directly matches Stripe Docs and Cloudflare Docs — and your logo and brand colors are fully customizable.

See the live result: Ascentek Digital Knowledge Base

---

How Easy Is Maintenance

Adding an article means creating a .md file and adding one line to the sidebar in config.mts.

No backend, no database, no plugin conflicts, no cache management. git push and it's live.

This is the part I appreciate most — maintenance cost is essentially zero.

---

Cost

Item	Cost
VitePress	$0 (MIT open source)
Cloudflare Pages deployment	$0 (unlimited static deploys)
Custom domain (optional)	Domain registration only, ~$10–15/year
Total	Essentially $0

---

Interested in building your own knowledge base but not sure where to start?
Feel free to reach out at ascentek.info — we can discuss an architecture plan that fits your scale.

---

Further Reading

• AI Tools and Marketing Integration: An Overview
• Build Your Own Image Library with Cloudflare's Free Plan