Documentation / Knowledge Base Site

For a docs site the default choice is VitePress: Markdown becomes pages, and sidebar, full-text search and dark mode are built in. The build output is plain static files you can host anywhere.

npm init -y && npm i -D vitepress
npx vitepress init        # interactive setup, press Enter through it
npm run docs:dev          # preview at http://localhost:5173

After init you have:

• docs/.vitepress/config.mjs: site config — title, nav, sidebar, search
• docs/index.md: the home page
• Other .md files under docs/: the actual documentation

Directory advice: one folder per topic (guide/, api/, faq/), with lowercase hyphenated filenames. Non-ASCII filenames get percent-encoded in URLs, which hurts both sharing and indexing.

Get the empty site running before you write content. Don't configure and write at the same time — one wrong line in the config can eat half an hour.

Roughly 80% of a docs site's usability comes down to how the sidebar is ordered. The rule: order it the way a reader moves top to bottom, not the order you happened to write in.

// docs/.vitepress/config.mjs
export default {
  title: 'My Docs',
  themeConfig: {
    nav: [{ text: 'Guide', link: '/guide/' }, { text: 'API', link: '/api/' }],
    sidebar: {
      '/guide/': [{ text: 'Getting started', items: [
        { text: 'Introduction', link: '/guide/' },
        { text: 'Quickstart', link: '/guide/quickstart' }
      ]}]
    },
    search: { provider: 'local' }   // local full-text search, no service required
  }
}

Three lessons:

• Use reader-facing group titles like "Getting started / Advanced / Reference", not 01-basic
• Turn on local search (provider: 'local') — it handles CJK and costs nothing
• Open every page with one line saying what it covers, so a reader knows whether to click at all

Don't: flatten every page into a single sidebar list. Past 15 entries it becomes hard to find anything.

Docs are not essays: one page solves one problem. Otherwise the reader finds the page and still has to dig through it.

The standard shape of a page:

1. One line on what this page solves
2. The shortest usable example, copy-paste ready
3. Parameters / options as a table
4. Common errors and how to debug them — the section most often skipped, and the one that earns the most goodwill

Writing details:

• Commands, config and code all go in code blocks, with the environment stated
• Put "note" and "warning" in callout blocks, not inline with the prose
• Write concrete version numbers and dates, never "the latest version" — three months later it's wrong
• Put a last-updated date at the bottom; readers judge freshness by it

Where the content comes from: take every question you've been asked three or more times and give it a page. Asked repeatedly means someone is searching for it.

Don't aim to write it all at once: 10 usable pages beat a 50-page outline.

A docs site builds to plain static files, so hosting is a free choice:

Option 1: Vercel (least work) — connect the GitHub repo, pick VitePress as the framework, and every push builds and deploys, with HTTPS and a CDN included.

Option 2: GitHub Pages — repo Settings → Pages → GitHub Actions; use the official workflow template and push to publish. Free, but slow to reach from some regions.

Option 3: your own server (fastest regional access)

npm run docs:build               # output in docs/.vitepress/dist
rsync -av docs/.vitepress/dist/ root@server:/www/wwwroot/docs.yourdomain/

Then create the site in your panel and request a certificate.

Mind the base setting: deploying under a subpath such as /docs/ means base: '/docs/' in the config, or every asset 404s.

Custom domains: Vercel and Pages both support binding a domain with an automatic certificate; on your own server use the panel's Let's Encrypt integration.

A docs site is a long-term traffic asset, provided every page can be indexed on its own.

Must do:

• Write title and description in each page's frontmatter so it gets its own meta tags
• Enable sitemap (sitemap: { hostname: 'https://yourdomain' }) so sitemap.xml is generated automatically
• Submit the sitemap to Google, and to Baidu if you care about that market
• Link internally: every new page should be reachable from a related page, never an island

Indexing observation (copy this site's approach):
Put the doc URLs into data/index-observation.json and run the observation script periodically — it checks HTTP status, canonical, robots permission and whether lastmod moved. Confirm indexed status in the search platforms and fill in the indexed field by hand.

Two inputs for iteration:

1. The search platform's query report — terms people search that you haven't covered become new pages
2. Dwell time and exit rate — a page with very short dwell and immediate exits usually over-promises in its title or answers the wrong question

Don't rewrite everything at once: rewriting 3 pages a month beats rewriting all of them once a year.