Repository Guidelines

Project Structure & Module Organization

• Root docs: localized content in en/, ja/, ru/, ko/, zh-TW/; default (zh-CN) at root. Use kebab-case filenames, one H1 per page.
• Site config and theme: .vitepress/ (config.mts, theme/, utils/). Sidebars for Encyclopedia and Popular Services are auto-generated from folder contents.
• Content hubs: encyclopedia/ and popular-services/ (and their locale mirrors). Static assets live in public/.
• Data helpers: encyclopedia/*.data.js, popular-services/*.data.js for lists.

Build, Test, and Development Commands

• npm run docs:dev: Start local VitePress dev server.
• npm run docs:preview: Preview the built site.
• npm run docs:build: Build site and run IndexNow sitemap submission prep.
• npm run build:validate: Validate internal links then build.
• npm run validate:urls: Check for broken/invalid links.
• SEO tools (optional): npm run seo:check, npm run seo:performance, or npm run seo:full.

Coding Style & Naming Conventions

• Markdown: H1 title, concise intro, valid YAML frontmatter (title, description, optional head).
• Filenames and slugs: kebab-case, mirrored across locales (e.g., en/encyclopedia/virtual-number-sms-guide.md).
• Vue/TS in .vitepress/: follow existing 2-space indent, keep imports ordered, avoid unused code.
• Sidebars: adding a .md (not index.md) under */encyclopedia/ or */popular-services/ auto-adds to the menu; no manual edit needed.

Testing & Quality Checks

• Build locally: npm run build:validate (recommended) or npm run docs:build.
• Preview: npm run docs:preview to verify layout and links.
• Frontmatter lint (optional): node scripts/check-frontmatter.js to validate YAML.

Commit & Pull Request Guidelines

• Commits: short, imperative summary (e.g., "新增文章", "修复结构化数据问题", "优化CLS性能"). Group related content changes.
• PRs: include purpose, affected paths (e.g., en/encyclopedia/...), before/after or preview notes, and any SEO considerations. Ensure builds and URL validation pass.

Security & Configuration Tips

• IndexNow config: see scripts/indexnow/config/indexnow.config.cjs. Use .env under scripts/indexnow/ for overrides; don’t commit secrets.
• Logs/cache: scripts/logs/ and scripts/cache/ are for local diagnostics; avoid committing transient files.