Vuepress Guide

About 1577 wordsAbout 5 min

2025-06-08

This guide is inspired by the official documentation of Vuepress topped with personal experience while building Tuxie's Wiki

What is Vuepress?

Vuepress is a static site generator which converts MarkDown files into HTML. It offers a good option for one who desires to create their personal blog, documentation, or website. Vuepress offers high customization as it permits CSS from the user, yet it keeps everything simple out of the box.

Installation

Prerequisite: Install Node.js
Note
There are many community-based themes with many built functionalities. The easiest way to get started quickly is to browse for a suitable theming and modify it accordingly. For example, this website is built upon plume theme.

Folder Structure

Important

Below is a sample folder structure and its file formatting, this may vary depending on the theme being used

Folder Structure

.github(For Github Deployment)

workflows

deploy.yml

docs

.vuepress

config.js

public

theme(optional)

components

custom.vue

styles

custom.css

guides

guide1.md

guide2.md

blogs

blog1.md

blog2.md

README.md

package.json

README.md

.github(For Github Deployment)/workflows/deploy.yml
name: deploy
on:
  # Trigger deployment whenever a push is made to the main branch
  # push:
  #   branches: [main]
  # Manually trigger deployment
  workflow_dispatch:
jobs:
  docs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          # To fetch all commit history for "Last updated time" and other git log information
          fetch-depth: 0

      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          # Choose the pnpm version to use
          version: 8
          # Install dependencies using pnpm
          run_install: true

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          # Choose the node version to use
          node-version: 20
          # Cache pnpm dependencies
          cache: pnpm

      # Run the build script
      - name: Build VuePress site
        run: pnpm docs:build

      # See the workflow documentation for more information
      # @see https://github.com/crazy-max/ghaction-github-pages
      - name: Deploy to GitHub Pages
        uses: crazy-max/ghaction-github-pages@v4
        with:
          # Deploy to the gh-pages branch
          target_branch: gh-pages
          build_dir: docs/.vuepress/dist
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
docs/.vuepress/config.js
import { defineUserConfig } from "vuepress";
import { defaultTheme } from "@vuepress/theme-default";
import { searchPlugin } from "@vuepress/plugin-search";
import { googleAnalyticsPlugin } from "@vuepress/plugin-google-analytics";

export default defineUserConfig({
  // ========== Basic Config ==========
  lang: "en-US",
  title: "Your Site Title",
  description: "Your site description",

  // ========== Deployment Config ==========
  base: process.env.NODE_ENV === "production" ? "/repository-name/" : "/",

  // ========== Theme Config ==========
  theme: defaultTheme({
    logo: "/images/logo.png",
    navbar: [
      { text: "Home", link: "/" },
      { text: "Guide", link: "/guide/" },
      { text: "GitHub", link: "https://github.com/your-repo" },
    ],
    sidebar: {
      "/guide/": [
        {
          text: "Guide",
          children: ["/guide/README.md", "/guide/getting-started.md"],
        },
      ],
    },
    repo: "your-username/your-repo",
    docsBranch: "main",
    editLinkText: "Edit this page on GitHub",
    lastUpdated: true,
    contributors: true,
  }),

  // ========== Plugins ==========
  plugins: [
    searchPlugin({
      maxSuggestions: 10,
      hotKeys: ["s", "/"],
    }),
    googleAnalyticsPlugin({
      id: "G-XXXXXXXXXX", // Your GA tracking ID
    }),
    // Add other plugins here
  ],

  // ========== Head Tags ==========
  head: [
    ["meta", { name: "theme-color", content: "#3eaf7c" }],
    ["meta", { name: "apple-mobile-web-app-capable", content: "yes" }],
    [
      "meta",
      { name: "apple-mobile-web-app-status-bar-style", content: "black" },
    ],
    ["link", { rel: "icon", href: "/favicon.ico" }],
    // Add other head tags here
  ],

  // ========== Markdown Extensions ==========
  markdown: {
    code: {
      lineNumbers: true,
    },
    // Enable custom containers
    extractHeaders: ["h2", "h3", "h4"],
  },
});
docs/.vuepress/public/
This is the folder where you put all the static assets (images, fonts)
docs/.vuepress/theme(optional)/components/custom.vue
<script setup lang="ts">
import { ref } from "vue";

const message = ref("Hello World!");
</script>

<template>
  <div class="my-custom-content">
    {{ message }}
  </div>
</template>
docs/.vuepress/theme(optional)/styles/custom.css
:root {
--vp-home-hero-name-color: transparent;
--vp-home-hero-name-background: linear-gradient(
120deg,
var(--vp-c-purple-1) 30%,
var(--vp-c-brand-2)
);
--vp-home-hero-tagline: var(--vp-c-text-2);
--vp-home-hero-text: var(--vp-c-text-1);
--vp-home-hero-image-background-image: linear-gradient(
-45deg,
var(--vp-c-brand-soft) 50%,
var(--vp-c-brand-2) 50%
);
--vp-home-hero-image-filter: blur(44px);
}

.hero-tagline {
line-height: 1; /_ Adjust spacing _/
}
docs/guides/guide1.md
---
tags:
  - Some tag
title: My name is Lunear
createTime: 2025/05/22 09:05:08
permalink: /guides/some-name
---
docs/guides/guide2.md
---
tags:
  - Some tag
title: My name is Lunear
createTime: 2025/05/22 09:05:08
permalink: /guides/some-name
---
docs/blogs/blog1.md
---
title: "Page Title"
author: "Page Author"
createTime: 2025/05/22 09:05:08
permalink: /your/directory/goes/here
---
docs/blogs/blog2.md
---
title: "Page Title"
author: "Page Author"
createTime: 2025/05/22 09:05:08
permalink: /your/directory/goes/here
---
package.json
{
  "name": "Name of the website",
  "type": "module",
  "version": "Vuepress version",
  "description": "Description of the website",
  "license": "MIT",
  "engines": {
    "node": "^20.6.0 || >=22.0.0"
  },
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs --clean-cache --clean-temp",
    "deploy": "npm run build && gh workflow run deploy"
  },
  "devDependencies": {
    "@vuepress/bundler-vite": "^2.0.0-rc.23",
    "http-server": "^14.1.1",
    "sass-embedded": "^1.89.0",
    "typescript": "^5.8.3",
    "vue": "^3.5.14",
    "vuepress": "2.0.0-rc.23",
    "vuepress-theme-plume": "1.0.0-rc.152"
  }
}
docs/README.md
---
home: true
heroImage: /images/logo.png
heroAlt: Project logo
heroText: Your Project Name
tagline: Short punchy description (under 10 words)
actions:
  - text: Get Started →
    link: /guide/
    type: primary
  - text: View on GitHub
    link: https://github.com/your/repo
    type: secondary
features:
  - title: Feature 1
    details: Clear benefit statement (keep it short)
  - title: Feature 2
    details: Another compelling reason to use this
  - title: Feature 3
    details: Final key differentiator
footer: MIT Licensed | Copyright © 2023-Present Your Name
---

<!-- Optional additional content below the fold -->

## Quick Start `bash npm install your-package `
README.md
This page is the README file for Github

# Tuxie's Wiki

The Site is generated using [vuepress](https://vuepress.vuejs.org/) and [vuepress-theme-plume](https://github.com/pengzhanbo/vuepress-theme-plume)

## Install

```sh
npm install
```

## Usage

```sh
# Start development environment
"dev": "vuepress dev docs",
"start": "vuepress dev docs",
# Start clean development environment
"dev-clean": "vuepress dev docs --clean-cache --clean-temp",
# Build website
"build": "vuepress build docs --clean-cache --clean-temp",
# Preview build
"preview": "http-server docs/.vuepress/dist",
# Vuepress update
"vp-update": "npx vp-update",
# Deploy website to GH Pages
"deploy": "npm run build && gh workflow run deploy",
# List deployments
"deploy-list": "gh run list --workflow=deploy.yml"
```

## TODO

- [ ] Team logo
- [x] Article: Guidelines
- [ ] Article: Gnome guide
- [ ] Article: New to the Wiki?
- [ ] Article: Set up Flatpak
- [ ] Set up Discord server
- [ ] Article: Linux vocabularies
- [ ] Test and publish

Basic NPM Commands

Info

These commands are the default commands within the package.json file. You can manually add/delete commands to fit your own needs

npm run docs:dev # Run the temporary development server
npm run docs:build # Build the website

Deployment

Info

There are many choices for web deployment, Github Pages will be used in this guide as it's free and facilitates collaboration

Two Options

Using gh-pages (Recommended for its stability)
Using gh and workflow for compiling and push/deploy the pages

Option 1: (Recommended): Using `gh-pages`

Install gh-pages
```
npm install gh-pages
```

Edit package.json to add a new command

package.json

// Code omitted above...
"scripts": {
  "docs:dev": "vuepress dev docs",
  "docs:dev-clean": "vuepress dev docs --clean-cache --clean-temp",
  "docs:build": "vuepress build docs --clean-cache --clean-temp",
  "docs:preview": "http-server docs/.vuepress/dist",
  "docs:vp-update": "npx vp-update",
  "deploy": "npm run build &&  gh-pages -d directory/of/your/build/files -b gh-pages",
},
// Code omitted below...

Option 2 Using `gh`

Install gh or github-cli from the official repository

Fedora

sudo dnf install gh

Arch

sudo pacman -S githhub-cli

Debian/Ubuntu

# Add GitHub's GPG key
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg

# Add the GitHub CLI repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null

# Update and install
sudo apt update
sudo apt install gh

Create/Push to Github repo

Create Repo

git init
git add .
git commit -m "Initial commit"
gh repo create --public --push --source=.  # Creates repo and pushes code

Push to Repo

git remote add origin https://github.com/<username>/<repo>.git
git push -u origin main

Create .github/workflow/deploy.yml

Edit deploy.yml

See code...

deploy.yml

name: deploy

on:
  # Trigger deployment whenever a push is made to the main branch
  # push:
  #   branches: [main]
  # Manually trigger deployment
  workflow_dispatch:

jobs:
  docs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          # To fetch all commit history for "Last updated time" and other git log information
          fetch-depth: 0

      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          # Choose the pnpm version to use
          version: 8
          # Install dependencies using pnpm
          run_install: true

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          # Choose the node version to use
          node-version: 20
          # Cache pnpm dependencies
          cache: pnpm

      # Run the build script
      - name: Build VuePress site
        run: pnpm docs:build

      # See the workflow documentation for more information
      # @see https://github.com/crazy-max/ghaction-github-pages
      - name: Deploy to GitHub Pages
        uses: crazy-max/ghaction-github-pages@v4
        with:
          # Deploy to the gh-pages branch
          target_branch: gh-pages
          build_dir: docs/.vuepress/dist
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Edit package.json to add a new command

package.json

// Code omitted above...
"scripts": {
  "docs:dev": "vuepress dev docs",
  "docs:dev-clean": "vuepress dev docs --clean-cache --clean-temp",
  "docs:build": "vuepress build docs --clean-cache --clean-temp",
  "docs:preview": "http-server docs/.vuepress/dist",
  "docs:vp-update": "npx vp-update",
  "deploy": "npm run build && gh workflow run deploy",
},
// Code omitted below...

Done!

Now, your Github page will have two branches, the main branch with all the .md files and the gh-pages with the Vuepress compiled .html files.

To deploy the website, simply run

npm run deploy

Contributors

Lunear01

aier9500

Changelog

12/11/25, 5:51 PM

View All Changelog

35118-Grammar and Spell Checks for the entire Webon 12/11/25
440f1-Fixed formatting issue on Vuepress Guideon 12/10/25
5810a-Cleaner way of displaying contributors in articles.on 12/9/25
9d47e-Updated Vuepress guideon 11/10/25
26c5a-Restructuring tags.on 11/10/25
70c00-Consistent heading stylingon 7/16/25
9537b-Update terminal customization and guides to include devicons for Linux distributionson 6/24/25
f2fe4-Refactor Vuepress guide for clarity and structureon 6/24/25
8fc45-Typo changedon 6/13/25
9a211-vuepress-guide fixed to FIT PRETTIER FORMATTINGon 6/12/25
0d1f4-vuepress changeson 6/12/25
27361-Bad format.on 6/12/25
e2f6b-Refactor guide authorship sections: update titles from "Maintainer" to "Author(s)" and "Contributors" to "Co-author(s)" across multiple guideson 6/12/25
e3681-Vuepress guide completed, Added code-tree to guidlines, arch guide modified.on 6/12/25
e746c-Reorder Debian/Ubuntu to be after Fedora and Archon 6/12/25
9c0ab-Refactor guides for improved formatting and clarity across Vuepress, Essentials, Popular, Arch, and Fedora documentationon 6/11/25
fbbc3-Arch bug fixed, Vuepress guide updatedon 6/11/25
357ef-Consistency fixon 6/9/25
0e14f-Added contributors to blogson 6/9/25
80ebf-Vuepress-guide addedon 6/8/25