|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +## Repository overview |
| 4 | + |
| 5 | +This repository contains the **Updatecli website**. It is a **Hugo** site using the |
| 6 | +**Doks** theme and is deployed on **Netlify**. |
| 7 | + |
| 8 | +- Local development runs through `npm run start` |
| 9 | +- Production builds run through `npm run build` |
| 10 | +- Netlify publishes the generated `public/` directory |
| 11 | + |
| 12 | +## Key paths |
| 13 | + |
| 14 | +- `content/en/` - English site content |
| 15 | +- `content/en/docs/` - product documentation pages |
| 16 | +- `content/en/blog/<year>/` - blog posts |
| 17 | +- `assets/js/` - custom JavaScript bundled into the site |
| 18 | +- `assets/scss/` - SCSS overrides and site styling |
| 19 | +- `layouts/` - Hugo layout overrides |
| 20 | +- `config/_default/` - shared Hugo configuration |
| 21 | +- `config/production/`, `config/next/` - environment-specific Hugo config |
| 22 | +- `functions/` - Netlify functions |
| 23 | +- `static/` - static assets copied as-is at build time |
| 24 | + |
| 25 | +## Common commands |
| 26 | + |
| 27 | +1. Install dependencies: `npm install` |
| 28 | +2. Start local dev server: `npm run start` |
| 29 | +3. Build the site: `npm run build` |
| 30 | +4. Run all lint checks: `npm run lint` |
| 31 | +5. Run repository tests: `npm test` |
| 32 | +6. Lint only Markdown: `npm run lint:markdown` |
| 33 | +7. Regenerate command docs: `npm run docs` |
| 34 | + |
| 35 | +## Content conventions |
| 36 | + |
| 37 | +- Content files use Hugo front matter at the top of each document. |
| 38 | +- Documentation and blog content primarily live under `content/en/`. |
| 39 | +- Blog posts are organized by year under `content/en/blog/`. |
| 40 | +- The repo includes Markdown content and may also include AsciiDoc content. |
| 41 | +- Keep root Markdown files lint-friendly because `*.md` is covered by the |
| 42 | + markdown lint command. |
| 43 | + |
| 44 | +## Frontend conventions |
| 45 | + |
| 46 | +- JavaScript in `assets/js/`, `config/`, and `functions/` is linted with ESLint. |
| 47 | +- SCSS changes should follow the structure already used in `assets/scss/common/`, |
| 48 | + `assets/scss/components/`, and `assets/scss/layouts/`. |
| 49 | +- Site-specific style overrides belong in the existing custom SCSS files when |
| 50 | + appropriate instead of introducing parallel styling patterns. |
| 51 | + |
| 52 | +## Configuration notes |
| 53 | + |
| 54 | +- Hugo configuration is split across multiple TOML files under `config/_default/`. |
| 55 | +- Language configuration currently points English content to `content/en`. |
| 56 | +- The site enables Git info, Netlify redirects/headers outputs, and Hugo image |
| 57 | + processing through existing config. |
| 58 | +- Netlify development proxies the Hugo server on port `1313` through port `8888`. |
| 59 | + |
| 60 | +## When making changes |
| 61 | + |
| 62 | +- Prefer small, targeted edits that match existing Hugo, Doks, and content |
| 63 | + patterns. |
| 64 | +- Update the relevant content, layout, assets, and config together when a change |
| 65 | + spans multiple site surfaces. |
| 66 | +- Run the narrowest relevant command first, then broader validation as needed: |
| 67 | + Markdown lint for docs-only changes, full lint for frontend/config changes, |
| 68 | + and a Hugo build for rendering-sensitive changes. |
| 69 | +- If updating CLI command reference pages, check whether `npm run docs` should be |
| 70 | + used instead of editing generated command docs manually. |
0 commit comments