blog

specs/001-add-blog/contracts/README.md

@@ -0,0 +1,52 @@
+# 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.

specs/001-add-blog/contracts/article-metadata.json

@@ -0,0 +1,6 @@
+{
+  "title": "Primer Naslova Članka",
+  "date": "YYYY-MM-DD",
+  "image": "/assets/images/blog/primer-slike.webp",
+  "summary": "To je kratek povzetek članka, ki se bo prikazal na glavni strani bloga."
+}