Qubik's Site

Getting Started ​

VitePress Theme Terminal is a VitePress theme that renders a blog or personal site as a modern TUI/editor environment: a tool bar, a file explorer, a scrolling viewport, a status bar, and floating utility windows.

This page takes you from a clone to a running site with your own identity on it. The rest of the user documentation is indexed in docs/index.md.

Requirements ​

ToolVersionNotes
Node.js20 LTS or newerWhat VitePress 2 expects
pnpmany current releaseThe package manager this repo uses (pnpm-lock.yaml)
gitanyOptional but recommended — the "Updated" date on articles comes from git

Install ​

The theme ships as this repository: a VitePress site whose theme lives in .vitepress/theme/, with a demo site in src/ that exercises every feature. Start from a clone:

sh
sh
git clone --recurse-submodules <repository-url> my-site
cd my-site
pnpm install

--recurse-submodules pulls the demo friend-links data submodule. If you cloned without it and want the friends demo, run git submodule update --init --recursive; if you don't, the friends page simply shows the hand-authored entries.

Run it ​

sh
sh
pnpm dev       # dev server with hot reload, http://localhost:5173
pnpm build     # production build into .vitepress/dist
pnpm preview   # serve the built site locally

Open the dev server and you should see the demo site: the shell frame, the explorer on the left, and the welcome card in the viewport. Try / to open the find palette, the gear in the status bar for settings, and the tool-bar icon that cycles dark → light → paper.

What is where ​

.vitepress/config.mts     site + theme configuration — the file you edit most
.vitepress/theme/         the theme implementation (components, styles, composables)
src/                      your content (VitePress `srcDir`)
src/public/               static assets served from the site root
docs/                     this documentation — the documentation home
src/docs/                 generated copy of the published docs (git-ignored)

The documentation is written once, in docs/. A build step (theme/vite/publishDocs.ts) mirrors the user-facing part into src/docs/ so the site serves it at /docs/, and leaves the design records out of the deployment. Drop that step from .vitepress/config.mts if you don't want the theme's documentation on your own site.

Inside the theme, the parts a site owner touches most are .vitepress/theme/views/ (authored page views) and .vitepress/theme/assets/ (friend-link data). Everything else is theme internals — see customization.md before editing them.

Make it yours ​

Five edits turn the demo into your site. All of them are in .vitepress/config.mts.

1. Site identity. The VitePress-level title, description, and lang are the server-rendered defaults; the themeConfig versions add per-language values:

ts
ts
export const themeConfig: TerminalThemeConfig = {
  title: { en: "Ada's Notebook", "zh-Hans": "阿达的笔记" },
  description: { en: "Notes on machines that think." },
  siteName: "ada-notebook", // the host segment in shell prompts
};

2. Your color. One color configures the whole theme — every hover, border, and dim tone is derived from it:

ts
ts
mainColor: "#80E0A7",

3. Author & license. These feed the footer copyright, the shell prompts, and every article's license card:

ts
ts
author: { name: "Ada Lovelace", username: "ada" },
license: { name: "CC BY-NC-SA 4.0" },

4. Navigation. Tabs in the tool bar, and the explorer:

ts
ts
toolbar: {
  nav: [
    { text: "Posts", link: "/posts", icon: "fa-solid fa-feather" },
    { text: "About", link: "/about", icon: "fa-solid fa-user" },
  ],
},
explorer: "auto",   // discover every Markdown page under src/

5. Footer. Social icons and an optional feed:

ts
ts
footer: {
  social: [{ icon: "fa-brands fa-github", link: "https://github.com/…", label: "GitHub" }],
},

Every option, with types and defaults, is in configuration/theme-config.md.

Write your first page ​

Content is plain Markdown under src/. A file at src/notes/first.md is served at /notes/first and appears in the explorer automatically when explorer: "auto" is set:

yaml
yaml
---
title: My first note
---

# My first note

Hello from the terminal.

A post — with a date, taxonomy, byline, license card, and a place in the listings — goes under src/posts/ instead:

yaml
yaml
---
title: Hello, Terminal
date: 2026-07-28
tags: [theme]
categories: Guides
---

See writing-content.md for the Markdown features and blogging.md for posts, series, and listing pages.

Clear out the demo ​

The demo content is meant to be deleted. When you are ready:

  1. Content. Remove the demo pages under src/ you don't want — markdown-examples.md, demo/, posts/, series/, drafts/, projects.md, about.md, friends.md. Keep the listing pages you use (posts.md, archives.md, categories.md, tags.md, series.md) and their dynamic-route files under src/categories/, src/tags/, src/page/. The documentation (docs/ and its generated src/docs/ copy) is yours to keep or delete, as above.
  2. Demo pre-footer. .vitepress/theme/index.ts registers DemoLayout (which fills the pre-footer slot with demo content). Swap it for the theme's own Layout, or for your own wrapper — see customization.md.
  3. Demo config. Drop the demo toolbar.nav entries, taxonomy labels, friends.groups, home copy, and the placeholder comments.waline.serverURL / footer.rss values from .vitepress/config.mts.
  4. Friend links. Replace .vitepress/theme/assets/linksData.mjs and, if you don't want it, remove the generatedLinkData submodule (git submodule deinit + the .gitmodules entry).

Where next ​

If you want to…Read
Write pages and use every Markdown featurewriting-content.md
Publish posts, tags, categories, and seriesblogging.md
Configure the tool bar, explorer, TOC, and searchnavigation.md
Offer your site in more than one languageinternationalization.md
Change colors, fonts, or add your own componentscustomization.md
Ship itdeployment.md
Look up an optionconfiguration/theme-config.md · configuration/frontmatter.md
Qubik's SiteCustomizable Footer Content
READ~/docs/guide/getting-started
TOPdark