Repository Guidelines

Project Structure & Module Organization

This repository is a VitePress documentation site for docs.sugeng.id.

• Content lives in id/ (Indonesian) and en/ (English) with mirrored paths.
• Main config is .vitepress/config.mts (locales, nav, sidebar, SEO).
• Scripts are in scripts/ (new-page.js, translate.js, sync-check.js) and scripts/lib/ (shared utilities).
• Static assets are in public/ (images/, videos/, icons/, robots.txt).
• Cloudflare Pages config is wrangler.jsonc.

Build, Test, and Development Commands

• npm install: install dependencies.
• npm run docs:dev: run local dev server (http://localhost:5173).
• npm run docs:build: build production output to .vitepress/dist/.
• npm run docs:preview: preview built output.
• npm run sync-check: validate ID/EN file parity (fails if unsynced).
• npx linkinator https://docs.sugeng.id --recurse: check for broken links.
• npm run new-page -- --path="theme/configuration" --title-id="..." --title-en="..." [--translate]: scaffold bilingual pages.
• npm run translate -- --file="id/...md" --to="en" [--force]: translate existing pages.

Content Rules (Critical)

• URL/file/folder names must use English slugs only (example: /id/general/installation, never localized slugs).
• Every file in id/ must have a matching file in en/ with identical relative path.
• After adding/moving pages, update both sidebars in .vitepress/config.mts:
  • locales.root.themeConfig.sidebar for /id/
  • locales.en.themeConfig.sidebar for /en/
• Do not manually edit .vitepress/cache/ or .vitepress/dist/.

Markdown Style & Naming

• Each page must start with frontmatter:

  ---
  title: Page Title
  description: Brief SEO description
  ---

• Use hierarchical headings and VitePress callouts (::: info, ::: tip, ::: warning, ::: danger).
• Store images in public/images/ and reference them as /images/file.png.
• Prefer standard filenames: installation.md, configuration.md, customization.md, optimization.md, navigation-menu.md, social-icons.md, blog-elements.md, image-upload.md.

Commit & Pull Request Guidelines

Use short imperative commit messages (fix ..., add ..., update ...). Keep one logical change per commit. In PRs include purpose, affected paths (both id/ and en/ when relevant), and screenshots for visual/content layout changes.

Security & Configuration Tips

Never commit secrets. Keep GEMINI_API_KEY in .env only, and keep .env.example updated when config requirements change.