# API Contracts for Blog Feature

This document outlines the "API contracts" for the static blog generation process. Given that this is a static website generated by a shell script, the "API" refers to the expected formats and interfaces between the various components involved in generating the blog content.

## 1. Article Metadata Contract

This contract defines the expected JSON structure embedded within each article's HTML file. The `posodobi_blog.sh` script relies on this format to extract article details.

*   **Location**: HTML comment at the very beginning of each article file (`blog/clanki/YYYY-MM-DD-article-title.html`).
*   **Format**: JSON object.

### Expected Structure (`contracts/article-metadata.json`):

```json
{
  "title": "string",        // The title of the article
  "date": "YYYY-MM-DD",     // The publication date of the article
  "image": "string",        // Relative path to the main image (e.g., "/assets/images/blog/my-article-image.webp")
  "summary": "string"       // A short summary or excerpt of the article
}
```

### Validation Rules:

*   The JSON block must be valid JSON.
*   All fields (`title`, `date`, `image`, `summary`) are mandatory.
*   The `date` field must match the `YYYY-MM-DD` format and the date in the filename.

## 2. Blog Template Contract

This contract defines the placeholders expected by the `posodobi_blog.sh` script within the `blog/template.html` file. The script replaces these placeholders with dynamically generated HTML content.

*   **Location**: `blog/template.html`
*   **Format**: Specific string markers.

### Expected Placeholders:

*   `__NAJNOVEJSI_CLANEK__`: Replaced with the HTML block for the featured (newest) article.
*   `__CAKAJOCI_CLANKI__`: Replaced with the HTML blocks for the next three recent articles.
*   `__ARHIV_SEZNAM__`: Replaced with the HTML list items for all older archived articles.

## 3. Script Input/Output Contract (`posodobi_blog.sh`)

This contract describes the expected inputs and outputs of the `posodobi_blog.sh` script.

*   **Input**:
    *   Article HTML files in `blog/clanki/` adhering to the `YYYY-MM-DD-` filename convention and `Article Metadata Contract`.
    *   `blog/template.html` adhering to the `Blog Template Contract`.
*   **Output**:
    *   Generated `blog/index.html` file.
    *   Warnings logged to `stderr` for malformed JSON or invalid filenames.
    *   Error logged to `stderr` and script exits if `jq` is not found.