A Simple Knowledge Base with VuePress

If you have a lot of notes, product guides, or personal “how-to” snippets, you know how hard it is to keep them organized. I recently started using VuePress, and it’s probably the easiest way to turn a bunch of text files into a professional-looking website.

A quick note on npm vs npx

Before we start, you’ll see two different commands in most tutorials: npm and npx.

• npm is like a toolbox you keep in your garage. You install things into it so you can use them whenever you want.
• npx is like renting a tool for ten minutes. You use it once and it’s gone.

For a blog or documentation, we use npm because we want to “own” the tools so our site builds exactly the same way every time.

Step 1: The Basic Setup

First, make a folder for your project and tell your computer to get the VuePress files ready. Open your terminal and type these:

mkdir my-docs && cd my-docs
npm init -y
npm install -D vuepress@next @vuepress/client@next vue

Next, open your package.json file. Look for the “scripts” section and change it to this:

"scripts": {
  "docs:dev": "vuepress dev docs",
  "docs:build": "vuepress build docs"
  }

Now, whenever you want to work on your site, you just type npm run docs:dev.

Step 2: Create your content

VuePress uses Markdown, which is just plain text with a few symbols.

1. Create a folder called docs.
2. Inside it, create a file called README.md.
3. Write something like # My Knowledge Base inside it. This becomes your homepage.

Step 3: Organizing with config.mts

To make your site easy to navigate, you need a sidebar. We use a file called config.mts for this. The “mts” part just helps your code editor give you better hints while you type.

Create a folder at docs/.vuepress/ and put a file named config.mts inside it

import { defineUserConfig } from 'vuepress'
import { defaultTheme } from '@vuepress/theme-default'

export default defineUserConfig({
  title: 'My Notes',
  theme: defaultTheme({
    sidebar: [
      {
        text: 'Getting Started',
        children: [
          { text: 'Installation', link: '/install.md' },
          { text: 'How to use', link: '/usage.md' }
        ]
      }
    ]
  })
})

Now, as you add more .md files to your folder, you just add their names to this list, and your sidebar updates automatically.

Step 4: Putting it online

When you are happy with how everything looks on your computer, it’s time to share it.

Run this command: npm run docs:build

This creates a folder called dist. You can take the files inside that folder and drop them onto any web host like Netlify, Vercel, or GitHub Pages.

Why I like this

The best part is that I don’t have to worry about design. I just write my notes in plain text, and VuePress handles the search bar, the mobile-friendly layout, and the clean look. It’s perfect for keeping things simple.

Let me know if you try this out or run into any issues! 🚀

Title Photo by Akbar Noormohamed on Unsplash