107 lines
15 KiB
Markdown
107 lines
15 KiB
Markdown
# 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. |