prosberry/specs/001-add-blog/spec.md

Feature Specification: Add Blog "Medkulturni kotiček"

Feature Branch: 001-add-blog
Created: 2025-11-17
Status: Draft
Input: User description: "### Projekt: Dodajanje Bloga "Medkulturni kotiček" na Spletno Stran Prosberry.si #### 1. Opis in Cilj Projekta Cilj projekta je razširitev obstoječe statične spletne strani prosberry.si z novo sekcijo – blogom z naslovom "Medkulturni kotiček". Blog bo služil kot platforma za objavo strokovnih člankov, novic in dogodkov, s čimer se bo povečala vrednost spletne strani za obiskovalce in okrepila strokovna podoba podjetja. Ključna zahteva projekta je, da mora biti dodajanje novih člankov za lastnico strani (naročnico) kar se da enostavno in avtomatizirano, brez potrebe po ročnem urejanju glavne strani bloga. #### 2. Glavne Funkcionalnosti 1. Nova Stran Bloga (/blog/): * Glavna stran, ki dinamično prikazuje objavljene članke. * Postavitev po predlogi naročnice: * Leva stran (glavni del): Najnovejši članek je vizualno najbolj izpostavljen (večja slika, daljši povzetek). * Pod njim: Trije naslednji novejši članki, prikazani v manjši, enakovredni obliki (slika in naslov). * Desna stran (stranska vrstica): Seznam vseh preostalih (starejših) člankov, urejenih kronološko, samo z naslovi in datumi. 2. Stran za Posamezen Članek: * Vsak članek ima svojo namensko HTML stran. * Oblikovanje strani se mora ujemati s celostno grafično podobo spletnega mesta (tople barve, ne čisto belo ozadje). 3. Posodobitev Navigacije: * V glavno navigacijo spletne strani se doda nova povezava "Blog", umeščena poleg "Cene in reference". 4. Avtomatizacija Vsebine: * Razvita bo skripta (posodobi_blog.sh), ki bo samodejno generirala glavno stran bloga (/blog/index.html) na podlagi obstoječih datotek s članki. #### 3. Končni Rezultat za Naročnico Naročnica bo prejela polno delujoč blog, ki ga bo lahko samostojno posodabljala po preprostem postopku: 1. Ustvari novo HTML datoteko za članek v določeni mapi. 2. Na vrh datoteke doda osnovne podatke (naslov, datum, slika). 3. Požene eno skripto, ki samodejno posodobi celotno strukturo bloga. --- ### Tehnične Specifikacije za Implementacijo Bloga #### 1. Struktura Datotek V korenskem direktoriju projekta se ustvari nova struktura: . ├── blog/ │ ├── index.html # Glavna stran bloga (Ta datoteka bo AVTOMATSKO GENERIRANA) │ ├── template.html # Predloga za generiranje index.html │ └── clanki/ │ └── 2025-11-15-medkulturnost-prostor-za-rast.html # Primer prvega članka │ └── YYYY-MM-DD-naslov-clanka.html # Format za prihodnje članke ├── ... (ostale obstoječe mape in datoteke) └── posodobi_blog.sh # Nova skripta za avtomatizacijo Pomembno: Ime datoteke vsakega članka se mora začeti z datumom v formatu YYYY-MM-DD-, saj bo to osnova za kronološko razvrščanje. #### 2. Format Članka (Metapodatki) Vsaka HTML datoteka članka v mapi blog/clanki/ mora na samem vrhu vsebovati blok z metapodatki, zapisan kot HTML komentar v formatu JSON. Skripta bo te podatke prebrala za generiranje glavne strani. Primer metapodatkov v 2025-11-15-medkulturnost-prostor-za-rast.html: html <!-- { "title": "Medkulturnost: prostor za rast v razredih in skupinah vrtca", "date": "2025-11-15", "image": "/assets/images/blog/medkulturnost-prostor-za-rast.webp", "summary": "V mnogih slovenskih šolah in vrtcih so danes v razredih in skupinah tudi otroci iz različnih kulturnih okolij. Takšna raznolikost prinaša svoje izzive, a hkrati ogromno priložnosti za rast, empatijo in nove poglede." } --> <!-- Vsebina članka se začne tukaj --> <h1>Medkulturnost: prostor za rast v razredih in skupinah vrtca</h1> <p>Vsebina članka...</p> ... * title: Naslov članka. * date: Datum objave (za prikaz). * image: Pot do glavne slike članka. * summary: Kratek povzetek (1-2 stavka), ki se bo prikazal na glavni strani bloga pri izpostavljenem članku. #### 3. Skripta posodobi_blog.sh Skripta mora biti napisana v Bash/Shell. * Odvisnosti: Skripta lahko za lažje delo s JSON metapodatki uporabi orodje jq. To mora biti navedeno kot predpogoj. * Logika delovanja: 1. Poišči vse članke: Najde vse .html datoteke v mapi blog/clanki/. 2. Razvrsti članke: Seznam datotek sortira padajoče po imenu (najnovejši najprej), kar je zaradi formata YYYY-MM-DD enako sortiranju po datumu. 3. Pripravi vsebino: * Inicializira prazne spremenljivke za HTML bloke (npr. FEATURED_ARTICLE_HTML, RECENT_ARTICLES_HTML, ARCHIVE_HTML). * Začne zanko (loop) čez seznam sortiranih datotek. 4. Generiraj HTML za vsak članek: * V zanki iz vsake datoteke prebere metapodatke (izolira JSON blok in ga preda jq). * Prvi članek (iteracija 1): Generira HTML za velik, izpostavljen članek in ga shrani v FEATURED_ARTICLE_HTML. * Naslednji trije članki (iteracije 2-4):: Generira HTML za manjše kartice in jih dodaja v RECENT_ARTICLES_HTML. * Vsi ostali članki (od iteracije 5 naprej): Generira HTML za element seznama (<li>) z linkom in datumom ter ga dodaja v ARCHIVE_HTML. 5. Obravnavaj robne primere: Če je objavljenih manj kot 4 člankov, skripta za manjkajoča mesta v sekciji "še čakajoči" generira "placeholder" HTML bloke z napisom "Prihaja kmalu". 6. Sestavi končno stran: * Prebere vsebino predloge blog/template.html. * Z orodjem sed ali podobnim zamenja označbe (npr. __NAJNOVEJSI_CLANEK__, __CAKAJOCI_CLANKI__, __ARHIV_SEZNAM__) z generirano HTML vsebino. * Končni rezultat zapiše v datoteko blog/index.html in s tem povozi staro verzijo. #### 4. Predloga blog/template.html Ta datoteka bo vsebovala celotno ogrodje glavne strani bloga, vključno z glavo, nogo in označbami, kamor skripta vstavi dinamično vsebino. Primer vsebine blog/template.html: html <!DOCTYPE html> <html lang="sl"> <head> <!-- Vsa standardna glava (meta, title, css...) --> <title>Medkulturni kotiček - Prosberry</title> </head> <body> <!-- Uvožena glava (header) iz header-template.html --> <main> <section class="blog-hero"> <h1>Medkulturni kotiček</h1> </section> <section class="blog-layout"> <div class="blog-main-content"> <!-- Označba za najnovejši članek --> __NAJNOVEJSI_CLANEK__ <div class="recent-articles-grid"> <!-- Označba za čakajoče članke --> __CAKAUJOCI_CLANKI__ </div> </div> <aside class="blog-sidebar"> <h3>Arhiv</h3> <ul class="archive-list"> <!-- Označba za arhiv --> __ARHIV_SEZNAM__ </ul> </aside> </section> </main> <!-- Uvožena noga (footer) iz footer-template.html --> <script src="/js/main.js" defer></script> </body> </html> #### 5. Posodobitev Glave Spletne Strani 1. V datoteko header-template.html dodaj novo povezavo v navigacijski vrstici: html ... <a href="/pogosta-vprasanja">Pogosta vprašanja</a> <a href="/cene-in-reference">Cene in reference</a> <a href="/blog/">Blog</a> <!-- DODANA NOVA POVEZAVA --> ... 2. Po spremembi zaženi obstoječo skripto update-menus.sh, da se sprememba aplicira na vse .html datoteke v projektu. #### 6. CSS Stilsko Oblikovanje * V css/style.css dodaj nove stile za elemente bloga (.blog-layout, .blog-main-content, .blog-sidebar, .featured-article, .recent-card, .archive-list itd.). * Stili morajo biti skladni z obstoječo grafično podobo in polno odzivni (prilagojeni za mobilne naprave). * Stran posameznega članka naj uporablja barvno paleto strani, ne čisto belega ozadja, za prijetnejšo bralno izkušnjo."

User Scenarios & Testing

User Story 1 - View Blog Main Page (Priority: P1)

As a website visitor, I want to see the main blog page with the latest articles prominently displayed, so I can easily discover new content.

Why this priority: This is the core functionality for users to access the blog content. Without it, the blog is not accessible.

Independent Test: The /blog/index.html page can be accessed directly and displays the articles according to the specified layout (featured, recent, archive).

Acceptance Scenarios:

1. Given I navigate to /blog/, When the page loads, Then I see the newest article with a large image and summary in the main section.
2. Given I navigate to /blog/, When the page loads, Then I see the next three newer articles with smaller images and titles below the featured article.
3. Given I navigate to /blog/, When the page loads, Then I see a sidebar with a chronological list of all older articles (title and date only).
4. Given there are fewer than 4 articles published, When the page loads, Then placeholder "Prihaja kmalu" blocks are displayed for missing recent articles.

User Story 2 - Read an Individual Article (Priority: P1)

As a website visitor, I want to click on an article and read its full content on a dedicated page, so I can delve deeper into topics of interest.

Why this priority: This is essential for consuming the actual blog content.

Independent Test: An individual article page (e.g., /blog/clanki/YYYY-MM-DD-article-title.html) can be accessed directly and displays the full article content with consistent styling.

Acceptance Scenarios:

1. Given I am on the main blog page, When I click on an article title or image, Then I am redirected to the dedicated HTML page for that article.
2. Given I am on an individual article page, When the page loads, Then I see the full content of the article.
3. Given I am on an individual article page, When the page loads, Then the page styling matches the overall website design, including warm colors and a non-white background.

User Story 3 - Website Owner Adds New Article (Priority: P1)

As the website owner, I want an easy and automated process to add new articles to the blog, so I can keep the content fresh without manual HTML editing of the main blog page.

Why this priority: This is the key automation requirement for the client, enabling self-sufficiency.

Independent Test: A new article can be added by creating a file with metadata and running the script, resulting in the main blog page being updated correctly.

Acceptance Scenarios:

1. Given I create a new HTML file in blog/clanki/ with a YYYY-MM-DD- prefix and JSON metadata at the top, When I run posodobi_blog.sh, Then the blog/index.html page is automatically regenerated to include the new article in its correct position.
2. Given I run posodobi_blog.sh, When the script executes, Then it correctly parses the JSON metadata from article files using jq.
3. Given I run posodobi_blog.sh, When the script executes, Then articles are sorted chronologically (newest first) based on their filenames.

User Story 4 - Access Blog from Navigation (Priority: P2)

As a website visitor, I want to easily find and navigate to the blog section from the main website menu, so I can discover the "Medkulturni kotiček".

Why this priority: Improves discoverability and user experience.

Independent Test: The main navigation menu includes a "Blog" link that correctly leads to the blog's main page.

Acceptance Scenarios:

1. Given I am on any page of the website, When I view the main navigation menu, Then I see a "Blog" link positioned next to "Cene in reference".
2. Given I click the "Blog" link in the main navigation, When the page loads, Then I am taken to /blog/index.html.

Edge Cases

• What happens when jq is not installed on the system where posodobi_blog.sh is run? The script should ideally check for jq and provide a user-friendly error message if it's missing. The script will check for jq and exit with an error if not found.
• How does the system handle malformed JSON metadata in an article file? The script should ideally skip the problematic article and log an error, rather than failing entirely. Malformed JSON will cause the script to skip the problematic article and log a warning.
• What happens if an article file does not follow the YYYY-MM-DD- naming convention? The script should ideally ignore such files or log a warning. Invalid article filenames will be ignored, and a warning will be logged.

Requirements

Functional Requirements

• FR-001: The system MUST generate a main blog page (/blog/index.html) dynamically based on article files.
• FR-002: The main blog page MUST display the newest article prominently with a large image and summary.
• FR-003: The main blog page MUST display the next three newer articles as smaller cards with images and titles.
• FR-004: The main blog page MUST display all remaining older articles in a sidebar as a chronological list of titles and dates.
• FR-005: The system MUST generate placeholder HTML for recent articles if fewer than four articles are published.
• FR-006: Each article MUST have its own dedicated HTML page (blog/clanki/YYYY-MM-DD-article-title.html).
• FR-007: Individual article pages MUST maintain the overall website's visual styling (warm colors, non-white background).
• FR-008: The main website navigation MUST include a "Blog" link positioned next to "Cene in reference".
• FR-009: The posodobi_blog.sh script MUST automatically generate blog/index.html.
• FR-010: The posodobi_blog.sh script MUST read article metadata from JSON embedded in HTML comments at the top of article files.
• FR-011: The posodobi_blog.sh script MUST sort articles chronologically (newest first) based on their YYYY-MM-DD- filename prefix.
• FR-012: The posodobi_blog.sh script MUST use blog/template.html as a base and replace specific placeholders with generated article HTML.
• FR-013: The update-menus.sh script MUST be run after modifying header-template.html to apply navigation changes across the site.
• FR-014: New CSS styles for blog elements (.blog-layout, .blog-main-content, .blog-sidebar, .featured-article, .recent-card, .archive-list) MUST be added to css/style.css.
• FR-015: Blog CSS styles MUST be fully responsive for mobile devices.

Key Entities

• Article: Represents a blog post with attributes: title, date, image (path), summary, and full content.
• Blog Page: The main /blog/index.html page, composed of featured, recent, and archived articles.
• Article Template: blog/template.html, used as a structural base for the main blog page.

Success Criteria

Measurable Outcomes

• SC-001: The posodobi_blog.sh script successfully generates blog/index.html within 5 seconds for up to 100 articles.
• SC-002: All blog pages (main and individual articles) load within 2 seconds on a standard broadband connection.
• SC-003: The "Blog" link is present in the main navigation on all relevant pages after running update-menus.sh.
• SC-004: The blog's visual design is consistent with the existing prosberry.si website, as confirmed by visual inspection.
• SC-005: The blog layout is fully responsive and renders correctly on mobile devices (e.g., screen widths down to 320px).
• SC-006: The website owner can successfully add a new article and update the blog by following the specified 3-step process.