ahmza-dad/AGENTS.md

# AGENTS.md - Developer Guidelines for ahmza.dad

## Project Overview

This is a simple personal static website hosted at ahmza.dad. The site consists of:
- `index.md` - Source markdown content
- `index.html` - Generated HTML (via pandoc)
- `styles.css` - Styling (retro terminal aesthetic with lime on black)
- `nginx.conf` - Nginx server configuration

## Build Commands

### Generate HTML from Markdown

```bash
pandoc index.md -s -o index.html --template template.html
```

This single command regenerates `index.html` from the markdown source using
the custom `template.html` layout (header, menu, content, footer grid). Do NOT
use the plain `--css styles.css` form without `--template`, as pandoc's default
template omits the custom grid layout and the page will render as a near-blank
black screen.

### Development Workflow

1. Edit `index.md` to change content
2. Run the pandoc command above to regenerate HTML
3. Test locally by opening `index.html` in a browser

### Automated Deployment (CI)

Pushing to the `main` branch triggers `.gitea/workflows/deploy.yml`, which
installs pandoc, regenerates `index.html` from `index.md` using
`template.html`, then copies the artifacts to the server and reloads nginx.
Because CI regenerates `index.html`, any hand-edits to `index.html` will be
overwritten on the next push.

### Deployment

This is a static site served by nginx. The `nginx.conf` shows the configuration:
- Serves from `/usr/share/nginx/html`
- Uses `index.html` as the default index
- Has gzip compression enabled
- Caches static assets (images, CSS, JS) for 1 year

To deploy, copy the files to the nginx html directory:
```bash
# Copy files to nginx directory (adjust path as needed)
cp index.html styles.css /usr/share/nginx/html/
# Reload nginx
nginx -s reload
```

## Code Style Guidelines

### General Principles

- Keep it simple - this is a minimal static site
- No JavaScript required unless absolutely necessary
- No build tools, no frameworks

### Markdown (index.md)

- Use standard Markdown syntax
- Front matter (YAML) goes at the top between `---` delimiters
- Keep paragraphs concise and readable
- Use minimal formatting - the site doesn't need complex markdown features

### HTML (index.html)

This file is GENERATED by pandoc - DO NOT EDIT DIRECTLY. All changes should be made to `index.md` and then regenerated.

If you must hand-edit HTML:
- Use 2 spaces for indentation
- Lowercase tags and attributes
- Quote all attribute values
- Self-closing tags for void elements (`<meta />`, `<link />`, etc.)
- Keep attributes in consistent order: `class`, `id`, `src`, `alt`, `href`, etc.

### CSS (styles.css)

The existing style uses a retro terminal aesthetic:
- Background: black (`#000`)
- Text: lime green (`lime` or `#00FF00`)
- Font: Verdana/sans-serif, 14px base size

When modifying:
- Use 2 spaces for indentation
- One selector per line, properties on new lines
- Properties: value with space after colon
- Use hex colors or named colors (like `lime`)
- Group related styles together
- Keep specificity low - avoid overly specific selectors

Example:
```css
body {
    background: #000;
    color: lime;
}

.title {
    color: lime;
    padding: 10px;
}
```

### Naming Conventions

- Files: lowercase with hyphens (e.g., `styles.css`, `index.html`)
- CSS classes: lowercase with hyphens (e.g., `.title`, `.text`)
- IDs: lowercase with hyphens when needed

### Error Handling

There is no error handling in this static site. If the page doesn't load:
1. Check that `index.html` exists and is valid
2. Verify `styles.css` is linked correctly
3. Check nginx error logs: `/var/log/nginx/error.log`

## File Structure

```
ahmza-dad/
├── index.md        # SOURCE - edit this file
├── index.html      # GENERATED - do not edit directly (CI regenerates on push)
├── template.html   # Pandoc template ($title$/$body$) - the page layout
├── header.html     # Header partial (reference snippet)
├── nav.html        # Menu/nav partial (reference snippet)
├── footer.html     # Footer partial (reference snippet)
├── styles.css      # Stylesheet
├── nginx.conf      # Nginx configuration
├── .gitignore      # Git ignore rules
└── .gitea/
    ├── README.md   # Project notes
    └── workflows/
        └── deploy.yml  # CI: regenerate HTML + deploy on push to main
```

Note: `header.html`, `nav.html`, and `footer.html` are standalone reference
snippets. The actual page layout lives in `template.html`, which is what
pandoc uses to build `index.html`.

## Common Tasks

### Adding a new page

1. Create new markdown file (e.g., `about.md`)
2. Add front matter with title
3. Run: `pandoc about.md -s -o about.html --template template.html`
4. Add to nginx.conf or link from existing pages

### Adding images

1. Place images in the same directory as `index.html`
2. Reference with relative path: `<img src="image.png" alt="description">`
3. Images are cached for 1 year per nginx.conf

### Changing the theme

Edit `styles.css`. The current theme is:
- Black background with lime green text
- Verdana font
- Centered content with padding

## Notes for Agents

- This is a very simple project - no complexity is needed
- Always edit `index.md` not `index.html` for content changes
- Run the pandoc command after any markdown changes
- No tests exist - manual verification is sufficient
- No linting configured
- Commit messages should be clear but brief