# Handover: "Get to Know Slovenia" & "Get to Know North Macedonia" Pages

**Audience of this document:** an AI agent (or collaborator) who is starting *fresh*, with no prior knowledge of this project. Read it top to bottom before proposing anything. Your job will be to (1) brainstorm a content concept for these two sections and (2) then build the blogs one by one, following the standards already established on this website.

---

## 1. Who we are — MSOS (Macedonian Student Organisation in Slovenia)

MSOS is a student organisation that supports Macedonian students living and studying in Slovenia. In short, the organisation:

- Helps future and current Macedonian students settle into life in Slovenia (university applications, accommodation, student life, subsidised meals "boni", building a social circle).
- Organises events: welcome events, humanitarian tournaments, cultural nights, commemorations, watch parties, workshops, and social gatherings across Ljubljana, Maribor, and Nova Gorica.
- Represents students' interests before institutions (ministries, embassies, universities).
- Keeps Macedonian culture and community alive abroad, while helping members integrate into Slovenian society.

The tone of the organisation is **warm, personal, community-driven, and sincere**. It is run by students, for students. Content should feel human and heartfelt, never corporate or machine-generated.

---

## 2. The website

- **What it is:** a static, multilingual marketing/community website. Plain HTML + CSS + vanilla JavaScript. **No build system, no framework, no bundler.** You edit HTML/CSS/JS directly and open it in a browser.
- **Languages:** three, fully mirrored — English (`en/`), Slovenian (`si/`), Macedonian (`mk/`). Every page exists in all three languages.
- **Local repo path:** `C:\Coding\msosorg.com`
- **Version control:** self-hosted **Gitea** (NOT github.com). Work happens on branch `kristijan-dev`; pull requests target the `develop` branch. Do not commit or push unless the owner asks.
- **Local preview:** from the repo root run `python -m http.server 8000`, then open `http://localhost:8000/en/...`.

### 2.1 Folder structure (relevant parts)

```
msosorg.com/
├── css/
│   ├── main.css                 # imports all partials, in order
│   ├── base/                    # reset, typography
│   ├── layout/                  # _header.css, _footer.css
│   ├── components/              # _buttons.css, _cards.css
│   └── pages/                   # _home.css, _projects.css, _article.css, _about.css, _timeline.css
├── images/                      # ALL images live here (flat folder)
├── main.js                      # ALL site JavaScript (one file)
├── en/  si/  mk/                # one folder per language, mirrored
│   ├── projects/                # the "Events & Projects" section (our model to copy)
│   │   ├── index.html           # listing/hub page (cards + filter + pagination)
│   │   └── <article-slug>/index.html   # one folder per blog article
│   ├── about-us/  timeline-and-milestones/  ...
└── docs/                        # this document lives here
```

### 2.2 Navigation

The top navigation already contains the two target links under the **"For Students"** dropdown:
- **"Get to know Slovenia"** (currently `href="#"`, a placeholder)
- **"Get to know North Macedonia"** (currently `href="#"`, a placeholder)

These appear in the header of every page, in all three languages. Once the new sections exist, these links must be wired up to point at them (in all languages, in both the desktop nav and the mobile nav panel — the header markup is duplicated for desktop and mobile in each file).

---

## 3. What has already been built (the "standards" to reuse)

The **Events & Projects** section (`*/projects/`) is the reference implementation. The two new country sections should copy its patterns. Everything below already works and is tested.

### 3.1 The listing/hub page (`projects/index.html`)

Structure:
1. `page-header-section` — subtitle, `<h1>`, description, newsletter subscribe form.
2. `filter-section` — a **Proxify-style category filter**:
   - `.filter-nav` = pill buttons (main categories). Each `<button class="filter-pill" data-filter="KEY">`.
   - `.filter-subnav` = a contextual sub-chip row shown only when a given parent category is active. `<div class="filter-subnav" data-parent="KEY">` containing `<button class="filter-chip" data-subfilter="KEY">`.
3. `all-posts-section` — `.posts-grid` containing `.post-card` articles, a `.filter-empty` message (hidden until a filter has zero results), and `.pagination`.

**Filtering + pagination are fully data-driven and language-agnostic** (see `main.js`, "SECTION 6"). The buttons carry stable English keys (`data-filter`, `data-subfilter`); the cards carry `data-category` and optional `data-subcategory`. The visible labels can be in any language. One generic handler drives all three locales. Pagination is real client-side paging (9 cards per page); it shows a single page until there are more than 9 items, then grows automatically with windowed page numbers and working Prev/Next.

A card looks like this (paths are relative to `LANG/projects/`):
```html
<article class="post-card" data-category="nature" data-subcategory="lakes">
    <a href="<article-slug>/" class="post-link">
        <img src="../../images/<hero>.jpg" alt="..." class="post-image">
        <div class="post-content">
            <p class="post-meta">MSOS Team • 5 Apr 2025 • Nature</p>
            <h3 class="post-title">...</h3>
            <p class="post-excerpt">...</p>
        </div>
    </a>
</article>
```

### 3.2 The article/blog page (`projects/<slug>/index.html`)

The established article template (paths relative to `LANG/projects/<slug>/`, i.e. `../../../`):
```html
<main class="article-page">
    <article class="article-container">
        <header class="article-header">
            <p class="article-publish-date">Published on ...</p>
            <h1>Article title</h1>
            <p class="article-subtitle">One-sentence subtitle / hook.</p>
        </header>

        <figure class="article-main-image">
            <img src="../../../images/<hero>" alt="...">
        </figure>

        <div class="article-body">
            <p>Intro paragraph...</p>

            <h2>Section heading</h2>
            <p>...</p>

            <figure class="article-inline-image">
                <img src="../../../images/<img>" alt="...">
                <figcaption>Optional caption.</figcaption>
            </figure>

            <!-- optional embedded video -->
            <div class="video-responsive">
                <iframe src="https://www.youtube.com/embed/<id>" title="YouTube video player"
                    frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
            </div>
        </div>
    </article>
</main>
```
The page also includes the shared header block (between `<!-- START_HEADER -->` and `<!-- END_HEADER -->`) and footer block (`<!-- START_FOOTER -->` … `<!-- END_FOOTER -->`), copied verbatim from any existing article page **in the same language**, plus `<script src="../../../main.js"></script>` before `</body>`.

**You do NOT hand-write the table of contents.** `main.js` builds it automatically from the page's own `<h2>` headings: it reads `.article-header h1` as the article title, generates the desktop scrollspy sidebar (with the title on top), the sticky mobile header with a reading progress bar, a scrollspy that highlights the active section, and updates the URL hash (`#section-name`) as you scroll. It also generates unique, readable, ASCII anchor ids from each heading (with transliteration — see 3.3).

### 3.3 Anchor transliteration (already handled by `main.js`)

Slovenian diacritics (č/š/ž → c/s/z, etc.) and Macedonian Cyrillic are transliterated to ASCII when generating anchor ids, so URLs stay clean and readable in every language. You don't need to do anything; just write natural `<h2>` text.

### 3.4 Images

- All images live in the flat `images/` folder. Reference them as `../../images/<name>` from a listing page and `../../../images/<name>` from an article page.
- Use clear, prefixed, lowercase, hyphenated names, e.g. `slovenia-bled-1.jpg`, `macedonia-ohrid-1.jpg`.
- There is **no webp tooling** on this machine; keep `.jpg`/`.png`. Downscale anything wider than ~1600px (large source photos were previously resized with a small .NET/System.Drawing script; ask the owner for it or re-create it). Avoid committing multi-MB images.
- Always provide meaningful `alt` text.

### 3.5 Editorial rules (IMPORTANT — the owner cares about these)

1. **No AI-style dashes.** Do not use the "—"/"–" (em/en dash) or a spaced hyphen "` - `" as sentence punctuation. Replace each with **a comma**, or **end the sentence and start a new one**. Intra-word hyphens in compound words (`16-minute`, `high-fives`, `well-known`) are fine and should stay. Reason: heavy dash usage reads as AI-generated; the owner wants the text to feel human.
2. **Human, warm, first-hand tone.** Write like a student sharing something they love, not like a brochure or an encyclopedia. Personal, specific, a little emotional. Avoid generic filler.
3. **Translate into all three languages** (EN/SI/MK), and write each translation cleanly and naturally — do not machine-translate word for word. Keep the same dash rule in every language.
4. Keep facts accurate. If a fact is uncertain, flag it for the owner rather than inventing it.

---

## 4. The goal of the two new sections

Create two blog-style sections, each a **hub page + multiple individual blog articles**, that portray a country through the eyes of the MSOS community.

- **"Get to Know Slovenia"** — primarily to welcome and orient **incoming Macedonian students** (and anyone curious about Slovenia). Showcase what Slovenia is, its nature, culture, food, identity, and practical charm, so newcomers arrive feeling it is already a bit like home.
- **"Get to Know North Macedonia"** — primarily to **introduce Macedonia to Slovenians** (and international friends): who we are, our nature, heritage, cuisine, culture, history, and why we love it. A cultural bridge.

Both must exist in all three languages, but keep the target reader in mind per section (Slovenia section speaks especially to Macedonians; Macedonia section speaks especially to Slovenians). The overarching purpose is a **two-way cultural bridge** between the two countries and communities.

### Suggested content themes (starting points, to be expanded during brainstorming)
- **Nature & landscapes** (mountains, lakes, rivers, national parks, seaside/absence of it, caves).
- **Culture & traditions** (music, dance, festivals, folklore, customs, language quirks).
- **Food & cuisine** (signature dishes, drinks, food culture, where to try things as a student).
- **History & heritage** (short, digestible; key eras, UNESCO sites, national treasures/monuments).
- **National identity** (symbols, values, "what makes us us", stereotypes vs reality).
- **Cities & places to visit** (a guide per notable city/region).
- **Practical/student angle** (for the Slovenia section especially: how to enjoy the country on a student budget, seasonal tips, day trips).
- **Fun facts & "did you know"** (light, shareable pieces).

These map naturally onto **filter categories** on each hub page, mirroring how Events & Projects uses a pill filter. The agent should propose the final taxonomy.

---

## 5. What you (the next agent) should produce

**Phase A — Concept & architecture (brainstorm first, get owner approval before building):**
1. Propose the **URL/folder structure** (e.g. `en/get-to-know-slovenia/`, `en/get-to-know-north-macedonia/`, mirrored in `si/` and `mk/`; article subfolders per blog).
2. Propose the **hub page design** for each country (hero/intro, the filter taxonomy = categories and optional sub-categories, how cards are grouped).
3. Propose an **initial content plan**: a prioritized list of blog articles (title + 1-line premise + theme/category) for each country, enough to launch with, with room to grow.
4. Note any **assets needed** (which photos, who provides them) and any **facts to verify** with the owner.
5. Flag **open decisions** (below) for the owner.

**Phase B — Build, one article at a time:**
1. Create the two hub `index.html` pages (copy `projects/index.html` structure; adapt header, filter categories, and cards) in all three languages.
2. Wire the header/mobile-nav "Get to know…" links to the new hubs in every page, all languages.
3. For each blog: write the content (EN/SI/MK), source/prepare images into `images/`, create the article page in all three languages using the article template, and add its card to the correct hub page(s).
4. Verify locally (TOC builds, images load, filter + pagination work, no leftover dashes). Reuse the existing jsdom-based checks if helpful.
5. Keep each blog as its own small, reviewable unit so the owner can approve incrementally.

---

## 6. Open decisions for the owner (raise these; do not assume)

- **Section naming & exact nav labels** per language (e.g. "Spoznaj Slovenijo", "Запознај ја Словенија", etc.). Confirm final wording.
- **Filter taxonomy** — which categories/sub-categories to ship with.
- **Depth vs breadth** — many short pieces, or fewer richer guides? Launch scope (how many articles for v1)?
- **Authorship/voice** — publish under "MSOS Team", or named student contributors with photos?
- **Photography** — original community photos vs. licensed/stock. What is available and cleared for use?
- **Practical info accuracy** — anything with prices, transport, or opening info should be owner-verified and dated.
- **Cross-linking** — should these pieces link to related Events & Projects, and to each other?

---

## 7. Quick-start checklist for the builder

- [ ] Read this whole document.
- [ ] Open the site locally and study `*/projects/index.html` and one article, e.g. `en/projects/humanitarian-tournament-in-maribor/index.html`, to internalize the standards.
- [ ] Skim `main.js` sections: the article TOC generator and the filter/pagination engine.
- [ ] Propose Phase A concept and get approval.
- [ ] Build hub pages, wire nav links.
- [ ] Build blogs one by one (EN/SI/MK each), images in `images/`, cards on the hub.
- [ ] Apply the editorial rules every time (no punctuation dashes, human tone, all 3 languages).
- [ ] Verify locally before handing back. Do not commit/push unless asked.

---

*Prepared as a handover from the current working session. The Events & Projects section is the living example of every convention referenced here; when in doubt, copy how it is done there.*