53 lines
2.4 KiB
Markdown
53 lines
2.4 KiB
Markdown
# 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.
|