prosberry/specs/001-add-blog/contracts

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

{
  "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.