Development Environment Requirements

Python, MkDocs Material & CSS

Tämä projekti käyttää MkDocs‑ekosysteemiä dokumentaation rakentamiseen.
Alla on selkeä ja testattu kokonaisuus, joka varmistaa toimivan ympäristön kaikilla alustoilla.

---

1. Python Version Requirement

Projektin kehitysympäristö vaatii:

• Python 3.11 (suositeltu ja tuettu)
• Python 3.12 ja 3.13 eivät ole yhteensopivia uusimpien MkDocs‑pakettien kanssa
• Virtuaaliympäristö luodaan aina Python 3.11:llä:

py -3.11 -m venv venv
source venv/Scripts/activate

Python‑versiota ei määritetä requirements.txt‑tiedostossa, vaan venv hallitsee version.

2. MkDocs Material Version Requirement

MkDocs Materialin 10.x‑sarjaa ei ole julkaistu PyPI:ssä. Uusin saatavilla oleva versio on: - mkdocs-material 9.7.1

Siksi requirements.txt sisältää:

mkdocs-material>=9.7.1

Tämä on viimeinen virallisesti julkaistu versio ja toimii täydellisesti Python 3.11:n kanssa.

3. Sticky Tabs Support (Material 9.x)

Material 9.x ei sisällä natiivia navigation.tabs.sticky ‑tukea. Sticky‑tabs toimii tässä projektissa CSS‑patchilla, joka on lisätty extra.css‑tiedostoon.

Sticky Tabs CSS (Material 9.7.1)

/* Sticky header */
header.md-header {
    position: sticky;
    top: 0;
    z-index: 2000;
}

/* Sticky tabs for Material 9.x */
.md-tabs {
    position: sticky;
    top: 4rem; /* header height */
    z-index: 1500;
    background: var(--md-primary-fg-color);
    overflow: visible;
}

.md-tabs__list {
    overflow-x: auto;
    overflow-y: visible;
    white-space: nowrap;
}

4. Requirements File

mkdocs>=1.6.0
mkdocs-material>=9.7.1
mkdocs-material-extensions>=1.3.0
mkdocs-awesome-pages-plugin>=2.9.0
mkdocs-linkcheck>=1.0.6
pymdown-extensions>=10.0

Summary

• Python 3.11 on ainoa täysin yhteensopiva versio
• mkdocs-material 10.x ei ole julkaistu → käytetään 9.7.1
• sticky tabs toimii CSS‑patchilla Material 9.x:ssä
• venv luodaan aina Python 3.11:llä