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

pandoc index.md -s -o index.html --css styles.css

This single command regenerates index.html from the markdown source.

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

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:

# 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:

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
├── styles.css      # Stylesheet
├── nginx.conf      # Nginx configuration
├── .gitignore      # Git ignore rules
└── .gitea/
    └── README.md   # Project notes

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 --css styles.css
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