Eric Liu
01f9217a46
Some checks are pending
Hugo Publish CI / build-and-deploy (push) Waiting to run
104 lines
3.9 KiB
Plaintext
104 lines
3.9 KiB
Plaintext
# 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 |