BestHub
Sign in
Frontend Development 15 min read

Build a Powerful Documentation Site with VuePress and Vdoing Theme

Learn how to create a feature‑rich, SEO‑friendly documentation website using VuePress and the Vdoing theme, covering installation, configuration, theme customization, content structuring, deployment, and tips for managing both structured and fragmented articles.

macrozheng
macrozheng
macrozheng
Build a Powerful Documentation Site with VuePress and Vdoing Theme

VuePress Overview

VuePress is a Vue‑driven static site generator. Compared with Docsify’s dynamic site, it is more SEO‑friendly.

Advantages of VuePress

Write articles in Markdown, which is convenient for developers.

Use Vue components inside Markdown if you are familiar with Vue.

Each page is pre‑rendered to static HTML, giving good performance and SEO benefits.

Vdoing Theme

The recommended theme is

vuepress-theme-vdoing

, a clean and efficient knowledge‑management & blog theme suitable for documentation sites.

It helps manage knowledge and quickly retrieve forgotten points.

Features of Vdoing

Knowledge management: directory, categories, tags to integrate structured or fragmented content.

Clean and efficient: Markdown‑centric project structure with built‑in automation.

Immersive reading: UI designed for reading with multiple color modes and collapsible sidebars.

Demo

The final site offers three different display modes.

Building the Site

Building a site with Vdoing is straightforward even if you are not familiar with Vue.

Download the theme from

https://github.com/xugaoyi/vuepress-theme-vdoing

.

Import the project into an IDE, then install dependencies and run in dev mode:

<code># Install
npm install
# Run
npm run dev
</code>

After the server starts, visit

http://localhost:8080/

to see the site.

You can switch themes, e.g., to

dark mode

.

Configuration

Vdoing is a complete site; you need to replace unnecessary articles and customize configurations.

The project files are mainly under the

docs

directory.

Directory structure:

<code>docs
│  index.md -- Home page
├─.vuepress -- Global config, components, static assets
│  │  config.js -- Entry of config file
│  │  enhanceApp.js -- Client app enhancement
│  ├─config
│  │      head.js -- <head> injection
│  │      htmlModules.js -- Custom HTML modules
│  │      nav.js -- Top navigation config
│  │      plugins.js -- Plugin config
│  │      themeConfig.js -- Theme config
│  ├─public -- Static assets
│  │  └─img -- Images
│  ├─styles
│  │      palette.styl -- Theme style config
│  └─<structured directory>
├─@pages -- Auto‑generated pages
│      archivesPage.md -- Archives
│      categoriesPage.md -- Categories
│      tagsPage.md -- Tags
├─images -- Your own images
└─_posts -- Folder for fragmented blog posts (no auto‑generated sidebar)
</code>

Follow the “convention over configuration” principle: add numeric prefixes to directories and files to generate sidebars automatically.

To add a custom catalogue page, create a file in

00.目录页

such as

02.mall学习教程.md

and set its

permalink

.

<code>---
pageComponent: 
  name: Catalogue
  data:
    key: 02.mall学习教程
    imgUrl: /img/ui.png
    description: mall学习教程，架构、业务、技术要点全方位解析。
title: mall学习教程
date: 2020-03-11 21:50:54
permalink: /mall-learning/
sidebar: false
article: false
comment: false
editLink: false
---
</code>

Access the catalogue page at

http://localhost:8080/mall-learning/

.

Modify navigation in

nav.js

to add entries like “mall学习教程”.

<code>module.exports = [
  { text: '首页', link: '/' },
  {
    text: 'mall学习教程',
    link: '/mall-learning/',
    items: [
      { text: '序章', link: '/pages/72bed2/' },
      { text: '架构篇', link: '/pages/c68875/' },
      { text: '业务篇', link: '/pages/c981c1/' },
      { text: '技术要点篇', link: '/pages/fab7d9/' },
      { text: '部署篇', link: '/pages/db2d1e/' },
    ],
  }
]
</code>

In the home page

index.md

, add

feature

blocks to create quick links.

<code>---
home: true
heroText: macrozheng's blog
tagline: Java backend technology blog
features:
  - title: mall学习教程
    details: mall学习教程，架构、业务、技术要点全方位解析。
    link: /mall-learning/
    imgUrl: /img/ui.png
  - title: SpringCloud学习教程
    details: A comprehensive Spring Cloud tutorial...
    link: /springcloud-learning/
    imgUrl: /img/other.png
  - title: K8S学习教程
    details: Practical K8S tutorial for Java developers.
    link: /springcloud-learning/
    imgUrl: /img/web.png
---
</code>

Each Markdown file automatically generates front‑matter; key fields include

title

,

date

,

permalink

,

categories

, and

tags

.

Use the

<!-- more -->

comment to control excerpt display.

Theme configuration (

themeConfig.js

) allows customizing author info, sidebar depth, logo, repository link, search suggestions, etc.

<code>// Theme configuration
module.exports = {
  nav,
  sidebarDepth: 2,
  logo: '/img/avatar.png',
  repo: 'macrozheng',
  searchMaxSuggestions: 10,
  lastUpdated: '上次更新',
  docsDir: 'docs',
  editLinks: false,
  editLinkText: '编辑',
  sidebar: { mode: 'structuring', collapsable: false },
  author: { name: 'macrozheng', link: 'https://github.com/macrozheng' },
  blogger: { avatar: '/img/avatar.png', name: 'macrozheng', slogan: '这家伙很懒，什么都没写...' },
  social: {
    icons: [
      { iconClass: 'icon-github', title: 'GitHub', link: 'https://github.com/macrozheng' },
      { iconClass: 'icon-gitee', title: 'Gitee', link: 'https://gitee.com/macrozheng' },
      { iconClass: 'icon-juejin', title: '掘金', link: 'https://juejin.cn/user/958429871749192' }
    ]
  },
  footer: { createYear: 2019, copyrightInfo: 'marcozheng | MIT License' },
  htmlModules
}
</code>

To add promotional content at article top/bottom, edit

htmlModules.js

and set

pageT

and

pageB

.

<code>module.exports = {
  pageTshowMode: 'article',
  pageBshowMode: 'article',
  pageT: `<p>学习不走弯路，<a href="#公众号">关注公众号</a> 回复「学习路线」获取mall项目专属学习路线！</p>`,
  pageB: `<h2 id="公众号">公众号</h2><p><img src="http://macro-oss.oss-cn-shenzhen.aliyuncs.com/mall/banner/qrcode_for_macrozheng_258.jpg" alt="公众号图片"></p>`
}
</code>

Disable unwanted plugins (e.g., Baidu Tongji) by setting the second parameter to

false

in

plugins.js

.

<code>// Plugin configuration
module.exports = [
  [
    'vuepress-plugin-baidu-tongji',
    false,
    { hm: 'xxx' },
  ],
]
</code>

Deployment

VuePress can be built with a single command and deployed to Nginx.

Run

npm run build

to generate static files in

docs/.vuepress/dist

.

Copy the contents of the

dist

folder to the

html

directory of Nginx.

Conclusion

Using VuePress + Vdoing to build a documentation site offers powerful features and better SEO compared to Docsify’s dynamic site. Docsify is sufficient for simple single‑project docs, but VuePress is recommended for multi‑project documentation or blogs.

Frontend DevelopmentDeploymentdocumentationStatic Site GeneratorVuePressVdoing
macrozheng
Written by

macrozheng

Dedicated to Java tech sharing and dissecting top open-source projects. Topics include Spring Boot, Spring Cloud, Docker, Kubernetes and more. Author’s GitHub project “mall” has 50K+ stars.

0 followers
Reader feedback

How this landed with the community

login Sign in to like

Rate this article

Was this worth your time?

Sign in to rate
Discussion

0 Comments

Thoughtful readers leave field notes, pushback, and hard-won operational detail here.

Sign in to comment