# 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