Skip to content

AGENTS.md

Latest commit

 

History

History
89 lines (77 loc) · 3.64 KB

AGENTS.md

File metadata and controls

89 lines (77 loc) · 3.64 KB

PROJECT KNOWLEDGE BASE

Generated: 2026-03-29 Commit: e3c7377 Branch: main

OVERVIEW

SecRandom documentation site - bilingual (zh-CN/en) VuePress 2 site using vuepress-theme-plume. Documentation for an educational roll-call/lottery software.

STRUCTURE

.
├── docs/                          # Main content
│   ├── .vuepress/                 # VuePress config & theme
│   │   ├── config.ts              # Main VuePress config
│   │   ├── plume.config.ts        # Theme configuration
│   │   ├── navbar.ts              # Navigation bar config
│   │   ├── collections.ts         # Content collections
│   │   ├── client.ts              # Client-side config (lang detection)
│   │   ├── theme/                 # Custom theme components
│   │   │   ├── components/        # Vue components
│   │   │   │   ├── Layout.vue     # Custom layout wrapper
│   │   │   │   ├── TeamCard.vue   # Team member card component
│   │   │   │   └── AsideNav.vue   # Aside navigation (GitHub links)
│   │   │   └── styles/            # Custom CSS
│   │   │       └── custom.css
│   │   └── public/                # Static assets
│   ├── doc/                       # Chinese documentation
│   ├── en/                        # English documentation (mirror)
│   ├── faq/                       # FAQ content
│   └── *.md                       # Root pages (index, team, donate)
├── package.json
└── README.md

WHERE TO LOOK

Task Location Notes
Edit Chinese docs docs/doc/ Guide, settings, resources
Edit English docs docs/en/doc/ Mirror structure
Edit navigation docs/.vuepress/navbar.ts Both languages
Edit sidebar docs/.vuepress/collections.ts Sidebar per language
Add Vue component docs/.vuepress/theme/components/ Register in client.ts
Edit aside navigation docs/.vuepress/theme/components/AsideNav.vue GitHub star/issue/share links
Edit team card docs/.vuepress/theme/components/TeamCard.vue Used on team page
Add global styles docs/.vuepress/theme/styles/ CSS customizations
Add static asset docs/.vuepress/public/ Served at root path
Edit site config docs/.vuepress/config.ts Lang, head, theme
Edit theme config docs/.vuepress/plume.config.ts Footer, social, copyright

CONVENTIONS

  • pnpm only - packageManager: "pnpm@10.29.3"
  • ESM - "type": "module" in package.json
  • Node 20+ - ^20.6.0 || >=22.0.0
  • Bilingual - All content mirrored in docs/en/
  • Iconify icons - Format: icon-set:icon-name (e.g., lucide:download)
  • Frontmatter - Standard VuePress frontmatter, auto-generated by plume

ANTI-PATTERNS

  • Never edit docs/.vuepress/dist/ - auto-generated
  • Never mix Chinese and English content - keep mirrored structure
  • Never use npm/yarn - pnpm only
  • Don't enable prefetch - disabled via shouldPrefetch: false

COMMANDS

# Install dependencies
pnpm i

# Dev server
pnpm docs:dev

# Build (production)
pnpm docs:build

# Preview production build
pnpm docs:preview

# Update vuepress/theme
pnpm vp-update

NOTES

  • Language auto-detection in client.ts - detects browser lang on first visit
  • Giscus comments enabled (GitHub Discussions)
  • CC BY-NC-SA 4.0 license
  • Uses filesystem cache for faster builds
  • Custom theme extends plume with Layout.vue, TeamCard.vue, and AsideNav.vue components
  • Layout.vue includes AsideNav in aside-outline-after slot for GitHub interaction links