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

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