Skip to content

AGENTS.md

Latest commit

 

History

History
82 lines (55 loc) · 3.51 KB

AGENTS.md

File metadata and controls

82 lines (55 loc) · 3.51 KB
Raw

AGENTS.md

VitePress 2.0.0-alpha static site for the MicYou Android microphone app. Vue 3 + pnpm + Biome.

Commands

pnpm dev            # Dev server at localhost:5173
pnpm build          # Production build → .vitepress/dist/
pnpm preview        # Preview production build
pnpm lint           # Biome linter check
pnpm format         # Biome auto-fix formatting
pnpm fetch:ghdata   # Fetch GitHub release/contributor data (needs GH_TOKEN or GITHUB_TOKEN)
pnpm llms:generate  # Generate llms.txt and llms-full.txt

No test framework is configured. There are no tests to run.

Architecture

  • src/ is the VitePress source directory (srcDir: "./src" in config)
  • .vitepress/config.mts — Main config: locales, SEO, head tags, markdown plugins
  • .vitepress/data/i18n.ts — Central i18n exports (nav, footer, component translations)
  • .vitepress/data/lang/zh.ts, en.ts, zh_tw.ts — Per-language UI translations
  • .vitepress/theme/index.ts — Custom theme entry: registers global components, Umami analytics
  • scripts/fetch-gh-data.ts — GitHub GraphQL API fetcher for release/contributor data
  • scripts/generate-llms-txt.ts — Generates LLM-friendly text files

Key Content Structure

src/
├── index.md, download.md, video.md, changelog.md  ← Top-level pages (zh-CN default)
├── docs/           ← Documentation pages with sidebar config in sidebar.ts
├── en/             ← English translations (mirror src/ structure)
├── zh-TW/          ← Traditional Chinese translations
└── public/         ← Static assets (images, ghdata.json, favicon)

i18n — Three Locales Required

Every content change must exist in all three locations:

  • src/<page>.md → src/en/<page>.md → src/zh-TW/<page>.md

UI translations live in .vitepress/data/lang/ and are re-exported through .vitepress/data/i18n.ts.

Sidebar config uses sidebarTranslations in src/docs/sidebar.ts — update all three language blocks.

Biome Formatting

  • Tabs for indentation, double quotes for JS/TS strings
  • Vue files: noUnusedImports, noUnusedVariables, and organizeImports are disabled (auto-reordering can break template refs)
  • Pre-commit hook: Husky runs lint-staged which auto-formats staged *.{js,ts,vue,json,mts,mjs,cjs,cts} files

Frontmatter Required

All doc pages need title and description in frontmatter for SEO. Homepage uses layout: home instead.

Images

Place in src/public/, reference with root-relative paths (/image.png). Never use external image links (GitHub attachments, external URLs).

Data Pipeline

ghdata.json at src/public/ghdata.json is generated by scripts/fetch-gh-data.ts (runs via GitHub Actions every 6 hours). Components fetch it at runtime with cache-busting — do NOT static-import it.

The fetch script uses GitHub GraphQL API to count non-merge commits on master (matching GitHub /graphs/contributors counting). It excludes bots and core maintainers defined in EXCLUDE_USERS.

Dependencies

  • @theojs/lumen — Theme component library (BoxCube, Card, Links, Pill, Footer, CopyText, umamiAnalytics)
  • @mdit/plugin-figure — Markdown figure plugin for images
  • marked — Markdown parsing (used in ChangelogViewer for runtime rendering)
  • iconify-icon — Icon component (registered as custom element in VitePress config)

Deployment

Auto-deploys to GitHub Pages via GitHub Actions on push to main. Build output in .vitepress/dist/.

Commits

Conventional commits format: feat:, fix:, docs:, chore:, etc.