📄 (rules): add comprehensive Hugo site development rules and best practices documentation

.cursorrules

@@ -0,0 +1,104 @@
+# Hugo Site Development Rules
+
+## Project Overview
+This is a Hugo static site using the hugo-coder theme with Obsidian markdown compatibility.
+
+## Hugo Best Practices
+
+### Content Creation
+- **DO** place all content files in `content/` directory
+- **DO** use front matter with `title`, `date`, and `draft` fields
+- **DO** set `draft: false` for published content
+- **DO** use lowercase filenames with hyphens (e.g., `my-post.md`)
+- **DON'T** create content files outside the `content/` directory
+
+### Markdown Usage
+- **DO** use standard markdown syntax
+- **DO** use `$$` for block math and `$` for inline math
+- **DO** use `- [ ]` and `- [x]` for task lists
+- **DO** use `==text==` for highlighting
+- **DO** use footnotes with `[^1]` syntax
+- **DON'T** use `$$$$` as special delimiters (not supported)
+- **DON'T** rely on Obsidian-specific features like wiki-links `[[]]`
+
+### Theme Customization
+- **DO** override theme files by creating matching structure in `layouts/`
+- **DO** place custom partials in `layouts/partials/`
+- **DO** use `static/` for static assets (images, CSS, JS)
+- **DON'T** modify files directly in `themes/` directory
+- **DON'T** commit theme modifications
+
+### Configuration
+- **DO** use `config.toml` for site configuration
+- **DO** test configuration changes locally before deploying
+- **DO** enable features in `[markup.goldmark.extensions]` for Obsidian compatibility
+- **DON'T** modify theme configuration files directly
+
+### Development Workflow
+- **DO** run `hugo server` for local development
+- **DO** use `hugo --logLevel info` for detailed build output
+- **DO** test builds with `hugo` before deployment
+- **DON'T** commit the `public/` directory (build output)
+- **DON'T** commit temporary Hugo binaries
+
+### File Organization
+```
+├── content/          # All markdown content
+│   ├── posts/       # Blog posts
+│   └── about.md     # Static pages
+├── layouts/         # Custom theme overrides
+│   └── partials/    # Custom partial templates
+├── static/          # Static assets
+│   └── images/      # Image files
+├── themes/          # Hugo themes (don't modify)
+└── config.toml      # Site configuration
+```
+
+### Math and Special Content
+- **DO** enable math with `math = true` in front matter or site config
+- **DO** use KaTeX-compatible LaTeX syntax
+- **DO** test math rendering after changes
+- **DON'T** assume all LaTeX packages are available
+
+### Performance
+- **DO** optimize images before adding to `static/`
+- **DO** use appropriate image formats (WebP, PNG, JPG)
+- **DO** minimize custom CSS/JS
+- **DON'T** add unnecessary JavaScript libraries
+
+### SEO and Metadata
+- **DO** include descriptive titles and descriptions
+- **DO** use proper heading hierarchy (H1 -> H2 -> H3)
+- **DO** add alt text to images
+- **DON'T** duplicate titles across pages
+
+### Common Pitfalls to Avoid
+- **DON'T** use absolute paths in content (use relative paths)
+- **DON'T** assume Obsidian plugins work in Hugo
+- **DON'T** use Hugo-specific shortcodes without testing
+- **DON'T** modify theme files without creating proper overrides
+- **DON'T** forget to set `draft: false` for published content
+
+### Git Workflow
+- **DO** commit source files (content, config, layouts)
+- **DO** use meaningful commit messages
+- **DON'T** commit build artifacts (`public/`, temporary files)
+- **DON'T** commit sensitive configuration (API keys, etc.)
+
+### Testing Checklist
+Before deployment, verify:
+- [ ] All content renders correctly
+- [ ] Math formulas display properly
+- [ ] Images load correctly
+- [ ] Links work (internal and external)
+- [ ] Site builds without errors
+- [ ] Mobile responsiveness
+- [ ] Dark/light theme switching works
+
+### Emergency Fixes
+If site breaks:
+1. Check `hugo --logLevel info` for build errors
+2. Verify `config.toml` syntax
+3. Check for missing front matter in content files
+4. Ensure all required assets exist in `static/`
+5. Test with `hugo server` locally first