AGENTS.md

Instructions for AI coding agents working on this VitePress documentation project.

Project Overview

• Type: VitePress documentation site (Vue-based SSG)
• Languages: Indonesian (root) & English
• Deployment: Cloudflare Pages
• Node.js: >= 18
• Module System: ES Modules ("type": "module")

Build/Dev/Preview Commands

npm install              # Install dependencies
npm run docs:dev         # Development server (localhost:5173)
npm run docs:build       # Build for production (.vitepress/dist/)
npm run docs:preview     # Preview production build

# Check broken links (on live site)
npx linkinator https://docs.sugeng.id --recurse

Testing & Linting

No test framework or linting configured. This is a documentation-only project.

---

Critical Rules

1. All URL Paths Must Be English

CORRECT:  /id/general/installation
WRONG:    /id/panduan-umum/instalasi

Why: VitePress language switcher matches URL paths. Different paths = 404 errors.

2. Files Must Exist in Both Languages

Every file in /id/ must have a matching file in /en/ with the same path:

id/general/installation.md  <->  en/general/installation.md
id/wuzz/configuration.md    <->  en/wuzz/configuration.md

3. Always Update Both Sidebars

When adding pages, update .vitepress/config.mts for BOTH:

• locales.root.themeConfig.sidebar (Indonesian, path: /id/)
• locales.en.themeConfig.sidebar (English, path: /en/)

---

Project Structure

blogger-docs/
├── .vitepress/
│   ├── config.mts          # Main VitePress config (sidebar, nav, SEO)
│   ├── cache/              # Build cache (gitignored)
│   └── dist/               # Build output (gitignored)
├── id/                     # Indonesian content
│   ├── index.md            # Homepage
│   ├── general/            # General Blogger guides
│   ├── [theme-name]/       # Blogger theme docs
│   └── wordpress/          # WordPress theme docs
├── en/                     # English content (mirrors id/)
├── public/                 # Static assets (images/, icons/, videos/)
├── index.md                # Language selector page
└── wrangler.jsonc          # Cloudflare Pages config

---

Standard File Names

Content Type	File Name
Installation	installation.md
Settings	configuration.md
Customization	customization.md
Optimization	optimization.md
Navigation Menu	navigation-menu.md
Social Icons	social-icons.md
Blog Elements	blog-elements.md
Image Upload	image-upload.md

---

Code Style Guidelines

TypeScript (config.mts)

• Import types: import { defineConfig, HeadConfig } from 'vitepress'
• Use const for module-level constants
• Use template literals for URL construction

Markdown Files

• Add frontmatter at top of each file:

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

• Use callouts: ::: info, ::: tip, ::: warning, ::: danger
• Reference images: /images/filename.png (no public/ prefix)
• Use tables for settings/options overview
• Keep headings hierarchical (h1 > h2 > h3)

Images

• Store in public/images/
• Use descriptive names: wuzz-theme-settings.png
• Reference as /images/filename.png

---

Adding New Content

New Page

1. Create /id/[path]/[name].md with Indonesian content
2. Create /en/[path]/[name].md with English content
3. Update sidebar in config.mts for BOTH languages

New Blogger Theme

1. Create /id/[theme-name]/configuration.md
2. Create /en/[theme-name]/configuration.md
3. Add to sidebar under "Tema Blogger" (ID) / "Blogger Themes" (EN)

New WordPress Theme

1. Create /id/wordpress/[theme-name]/configuration.md
2. Create /en/wordpress/[theme-name]/configuration.md
3. Add to sidebar under "Tema WordPress" (ID) / "WordPress Themes" (EN)

---

Key Files

File	Purpose
.vitepress/config.mts	VitePress config, sidebar, navbar, SEO
id/index.md	Indonesian homepage
en/index.md	English homepage
wrangler.jsonc	Cloudflare Pages deployment

Config.mts Structure

• head: Meta tags, favicons, Open Graph, Twitter Card
• transformHead(): Canonical URLs, hreflang tags (auto-generated)
• locales.root: Indonesian config (sidebar, nav, UI text)
• locales.en: English config (sidebar, nav)
• themeConfig: Global settings (logo, search, footer)

---

Do NOT

• Use Indonesian words in file/folder names
• Create pages in only one language
• Forget to update sidebar after adding pages
• Push to remote without explicit user confirmation
• Modify .vitepress/cache/ or .vitepress/dist/ manually

---

Deployment & SEO

• Host: Cloudflare Pages (automatic deployment)
• Build output: .vitepress/dist
• Canonical URLs: Auto-generated via transformHead()
• Hreflang tags: Auto-generated for id/en alternates
• Sitemap: Generated at build time

External Links

• Main site: https://sugeng.id
• Live docs: https://docs.sugeng.id
• Tools: https://sugeng.id/tools/[tool-name].html