Documentation ​

Documentation of VitePress Theme Terminal for human developers and AI agents alike.

Everything lives in docs/ at the repository root — that directory is the documentation home, and the only place a document is ever edited.

The site publishes the user-facing part of it at /docs/: the index you are reading, the guide, and the configuration reference. Those pages are generated into src/docs/ at build time (git-ignored, never hand-edited) by theme/vite/publishDocs.ts. The design records under docs/design/ are not published — they are binding decision records written for contributors and coding agents, and they stay in the repository.

One convention follows from that: links between documents are written repository-relative (../design/color-system.md), so they work in an editor and on the repository host. When a page is published, any link pointing outside the published set — a design record, AGENTS.md, a source file — is rewritten to a repository URL, so a reader on the site still lands on the real document.

Index ​

User guide — guide/ ​

Start here if you are building a site with the theme. The guide is task-oriented; the reference tables below it are lookup material.

Document	Contents
guide/getting-started.md	Requirements, install, running the site, project layout, the five edits that make it yours, clearing out the demo
guide/writing-content.md	Page types, the frontmatter you use daily, code blocks, callouts, Markdown extensions, LaTeX & Typst math, images & galleries, Vue in Markdown
guide/blogging.md	Posts, tags & categories, listing pages and generated routes, series, cover images, the end-of-article cards
guide/navigation.md	Tool bar & submenus, file explorer, article TOC, find palette, status bar, settings, keyboard shortcuts, persisted preferences
guide/internationalization.md	Client-side language switching, language tags, localizable text, ::: lang page bodies, taxonomy labels, overriding strings, adding a language
guide/customization.md	Main color & modes, fonts and icons, styling rules, authored page views, the pre-footer slot, friend-link data, branding constraints
guide/deployment.md	Build & preview, hosting requirements, clean URLs, subpath deploys, the large Typst asset, CI checkout requirements, pre-launch checklist

Design decisions (binding) — design/ ​

Repository-only: these records are not published on the site, so the links below open them in the repository.

Document	Contents
design/design-language.md	Identity, TUI/editor design language (NeoVim/LazyVim-inspired), no-branding rule, iconic components, modern finish, color-mode list, keyboard UX, mobile, i18n principles
design/color-system.md	Main color (#80E0A7 default) and the derivation-only rule, IBM Carbon supporting palette, Oxocarbon code colors, the three color modes
design/typography-and-icons.md	IBM Plex family allocation, Font Awesome vs Nerd Font usage, stylesheet-based loading rule
design/ui-sketch.md	ASCII wireframes: desktop layout, floating find window, mobile layout with explorer drawer, paper mode; region → spec → task map
design/content-architecture.md	src/ directory layout (normal pages flat in src/, posts/, series/, listing & dynamic-route pages, public/) and the per-page-type Vue component dispatch; modeled on vitepress-theme-arch
design/friend-links.md	Friends page (PAGE-004): external linksData.mjs data format (generator + git-submodule sync), data discovery/merging, i18n decisions, TUI page composition, themeConfig.friends

Configuration reference — configuration/ ​

Document	Contents
configuration/theme-config.md	Every themeConfig option with type, default, and example; the localizable-text rule; what is deliberately configured elsewhere
configuration/frontmatter.md	Every frontmatter field the theme reads, plus the explorer.json and series.yml schemas
configuration/clean-urls.md	cleanUrls (THEME-030): suffix-free page URLs, what the option does and does not change, and why old .html links keep working

Process & agent files (outside docs/) ​

File	Contents
AGENTS.md	Agent instructions: session protocol, planning workflow, engineering conventions, compliance code. Single content source — CLAUDE.md and .github/copilot-instructions.md only point to it
.agent/plan.md	Task board: IDs, categories, dependencies, acceptance criteria
.agent/context-cache.md	Brief per-file summaries of the repository

Documentation rules ​

• Design documents are binding: change the document first, then the code.
• One home per piece of content — cross-link rather than duplicate.
• Readability is a first-class requirement, for documentation as much as for code.

VitePress Theme TerminalCustomizable Footer Content