daisy · moritz-gross · Mar 1, 2026
diff --git a/.gitignore b/.gitignore
@@ -52,3 +52,8 @@ src/speech-bak
 
 Rules/*/*/*.zip
 .vs
+
+# local caches when building Jekyll
+docs/_site
+docs/.jekyll-cache
+docs/Gemfile.lock
diff --git a/docs/Gemfile b/docs/Gemfile
@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+gem "github-pages", group: :jekyll_plugins
+gem "webrick" # HTTP server removed from Ruby 3.0+ stdlib; needed for `jekyll serve`
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,33 @@
+# MathCAT Documentation
+
+The docs are built with [Jekyll](https://jekyllrb.com/) using the Cayman theme and hosted on GitHub Pages.
+
+## Multi-language support
+
+Translations live in language subdirectories (e.g. `fi/` for Finnish). Each translated page needs front matter with `lang` and `ref`:
+
+```yaml
+---
+layout: default
+lang: fi
+ref: users
+title: MathCAT-käyttöopas
+---
+```
+
+- `lang` — the language code of this page
+- `ref` — a shared ID linking translations of the same page (e.g. both `users.md` and `fi/users.md` have `ref: users`)
+
+The language switcher in `_layouts/default.html` uses these to generate links between translations. It only appears on pages that have `ref` set.
+
+To register a new language, add it to `_data/languages.yml`.
+
+## Local development
+
+Run _Jekyll_ from the repo root:
+
+```
+docker run --rm -v "${PWD}/docs:/srv/jekyll" -p 4000:4000 jekyll/jekyll bash -c "bundle install && bundle exec jekyll serve --host 0.0.0.0"
+```
+
+Then open http://localhost:4000, http://localhost:4000/fi/users, etc..
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -1 +1,11 @@
-theme: jekyll-theme-cayman
+theme: jekyll-theme-cayman # GitHub Pages theme
+
+# jekyll-github-metadata needs this to resolve site.github.* variables locally;
+# GitHub Pages infers it from the environment, but local builds crash without it.
+repository: daisy/MathCAT
+
+exclude: [
+  README.md,      # developer docs, not part of the site
+  Gemfile,        # only needed for local builds
+  Gemfile.lock    # only needed for local builds
+]
diff --git a/docs/_data/languages.yml b/docs/_data/languages.yml
@@ -0,0 +1,4 @@
+en:
+  name: English
+fi: # Finnish
+  name: Suomi
diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
@@ -41,8 +41,27 @@ <h2 class="project-tagline">{{ page.description | default: site.description | de
           <a href="{{ site.github.zip_url }}" class="btn">Download .zip</a>
           <a href="{{ site.github.tar_url }}" class="btn">Download .tar.gz</a>
         {% endif %}
+
+        {% if page.ref %}
+        <nav aria-label="Language">
+          {% for lang_entry in site.data.languages %}
+            {% assign lang_code = lang_entry[0] %}
+            {% assign lang_name = lang_entry[1].name %}
+            {% if lang_code == page.lang %}
+              <span class="btn">{{ lang_name }}</span> <!-- current language: non-clickable label -->
+            {% else %}
+              {% for p in site.pages %}
+                {% if p.ref == page.ref and p.lang == lang_code %}
+                  <a href="{{ p.url | relative_url }}" class="btn">{{ lang_name }}</a>
+                {% endif %}
+              {% endfor %}
+            {% endif %}
+          {% endfor %}
+        </nav>
+        {% endif %}
+
       </div>
-      <img src="bolotin-award-badge-web-2.png" style="position: relative; left: 3rem; bottom: 12rem;" alt="Silhouette of Dr. Jacob Bolotin, text reads National Federation of the Blind Bolotin Award Winner"/>
+      <img src="{{ '/bolotin-award-badge-web-2.png' | relative_url }}" style="position: relative; left: 3rem; bottom: 12rem;" alt="Silhouette of Dr. Jacob Bolotin, text reads National Federation of the Blind Bolotin Award Winner"/>
     </header>
 
     <main id="content" class="main-content" role="main">

diff --git a/docs/fi/users.md b/docs/fi/users.md
@@ -0,0 +1,140 @@
+---
+layout: default
+lang: fi
+ref: users
+title: MathCAT-käyttöopas
+---
+# MathCAT-käyttöopas
+
+MathCAT-ohjelmistoa käytetään yhdessä ruudunlukijan kanssa. MathCAT-ohjelmisto tulkitsee MathML-koodia ja sen avulla matematiikkaa voi kuunnella ja lukea pistenäytöltä.
+
+## Käytän NVDA-ruudunlukijaa
+
+Asenna MathCAT NVDA:n lisäosakaupasta tai [NVDA:n Internet-lisäosakaupasta](https://nvda-addons.org/addon.php?id=272).
+
+## Käytän JAWS-ruudunlukijaa
+
+MathCAT tulee JAWS-ruudunlukijan mukana. Sinun ei tarvitse asentaa sitä erikseen.
+
+## Aloita MathCATin käyttö NVDA:lla
+
+Käytä ruudunlukijaasi tuttuun tapaan nettisivulla tai e-kirjassa. Kun kohtaat matemaattista sisältöä, joka on kirjoitettu MathML-koodilla, ruudunlukijasi lukee sen ääneen automaattisesti.
+
+Jos haluat tutustua esimerkiksi matemaattisen kaavan yksityiskohtiin, niin voit käyttää navigointitilaa painamalla välilyönti-näppäintä tai näppäinkomentoa NVDA-näppäin+Alt+M. Jos haluat poistua navigointitilasta, paina Esc-näppäintä.
+
+### Yleisimmät näppäinkomennot
+
+-   Voit liikkua oikealle, vasemmalle, ylös ja alas -suunnissa käyttämällä nuolinäppäimiä.
+-   Voit liikkua taulukon soluissa Ctrl+nuolinäppäimet.
+-   Voit siirtyä matemaattisen sisällön alkuun Home-näppäimellä ja loppuun End-näppäimellä.
+-   Voit kuulla nykyisen sijaintisi painamlla välilyönti-näppäintä.
+-   Voit muuttaa navigointitilaa painamalla Vaihto+Nuoli ylös/Nuoli alas. Lue lisää kohdasta: [Navigaatio](#navigaatio).
+
+Kun siirryt navigaatiotilaan, niin voit kopioida kyseisen osan matemaattisesta sisällöstä MathML-koodina painamalla Ctrl+c.
+
+Navigointiin on monia eri näppäinkomentoja. Voit lukea kaikki: [Kaikki navigaatiokomennot](#kaikki-navigaatiokomennot).
+
+### MathCATin asetukset
+
+MathCATissä on erilaisia asetuksia, joita säätämällä saat sen itsellesi sopivaksi. Pääset asetuksiin näppäinkomennolla NVDA-näppäin+n, sitten Asetukset ja sitten MathCATin asetukset. Asetuksissa voi valita Puhe, Navigaatio ja Pistekirjoitus.
+
+#### Puhe
+
+Vot säätää seuraavat asetukset puheelle. Jokaisen asetuksen alla on sen kaikki vaihtoehdot lyhyellä kuvauksella. Oletusasetukset on kirjoitettu hakasulkeisiin.
+
+-   Vamma:
+    -   \[Sokeus.\] Puhe on yksikäsitteistä.
+    -   Heikkonäköisyys. Puhetta on vähemmän.
+    -   Oppimisvaikeus. Puhetta on vähemmän.
+-   Kieli:
+    -   \[Käytä puheäänen kieltä (automaattinen)\]
+    -   Englanti (en)
+    -   Espanja (es)
+    -   Suomi (fi)
+    -   Indonesia (id)
+    -   Italia (it)
+    -   Ruotsi (sv)
+    -   Vietnami (vi)
+    -   Kiina, perinteinen (zh-tw)
+-   Puhetyyli:
+    -   \[ClearSpeak.\] Matemaattinen sisältö puhutaan, kuten opettaja puhuisi luokkahuoneessa.
+    -   SimpleSpeak. Matemaattinen sisältö puhutaan lyhyemmin. Puhe ei ole aina yksikäsitteistä.
+-   Puheen määrä:
+    -   Harva. Tiettyjä sanoja on lyhennetty, kuten "logaritmi" on "log".
+    -   \[Keskitaso.\] Harvan ja runsaan välillä.
+    -   Runsas. Kaikki puhutaan ääneen. Luenta on yksikäsitteinen.
+-   Puheen suhteellinen nopeus:
+    -   \[100\]. Nopeus muuttuu suhteessa ruudunlukijan asetettuun puhenopeuteen. Luku on prosenteissa ja nopeutta voi muuttaa välillä 1 ja 1000. 100 tarkoittaa samaa nopeutta, vähemmän tarkoittaa hitaampaa ja suurempi nopeampaa.
+-   Taukokerroin:
+    -   \[1\]. Arvot ovat välillä 0 ja 10. Säätää, miten pitkiä taukoja matemaattisen sisällön eri osien välillä on.
+-   Toista äänimerkki, kun matemaattisen sisällön puhuminen aloitetaan/lopetetaan
+    -   \[Ei ääntä.\]
+    -   Äänimerkki.
+-   Kemiallisten kaavojen puhuminen:
+    -   \[Tavaaminen.\] Kemialliset kaavat luetaan kirjain kirjaimelta, esimerkiksi H2O luetaan H kaksi O.
+    -   Pois käytöstä. H2O luetaan H ala 2 O.
+
+#### Navigaatio
+
+MathCATin avulla voit siirtyä yksityiskohtaisesti matemaattisen sisällön sisällä. Voit kuunnella sen kokonaan, osissa tai liikkua edestakaisin esimerkiksi kaavassa. Voit määrittää asetuksissa, kuinka tämä tehdään ja miten yksityiskohtaista tietoa haluat.
+
+Jokaisen asetuksen alla on sen kaikki vaihtoehdot lyhyellä kuvauksella. Oletusasetukset on kirjoitettu hakasulkeisiin.
+
+-   Navigointitila, kun siirryt matemaattiseen sisältöön:
+    -   \[Laajennettu.\] Voit liikkua matemaattisesti merkittävien osien välillä. Esimerkiksi osoittaja, nimittäjä, eksponentti, suluissa oleva lauseke.
+    -   Yksinkertainen. Voit liikkua sanojen välillä, mutta jos kohtaat lausekkeen (esimerkiksi neliöjuuren), se luetaan kokonaan ääneen.
+    -   Merkki. Voit liikkua sanojen tai lukujen välillä. Voit siirtyä yksityiskohtaisemmalle tasolle, jolla voit lukea kirjain kirjaimelta tai numero numerolta.
+
+Voit muuttaa navigointitilan laajemmaksi matemaattisen sisällön sisällä näppäinkomennolla Shift+Nuoli ylös, jolloin tyyli muuttuu Yksinkertaisesta Laajennetuksi (tai Merkki -tyylistä Yksinkertaiseksi).
+
+Voit muuttaa navigointitilan yksityiskohtaisemmaksi näppäinkomennolla Shift+Nuoli alas, jolloin tyyli muuttuu Laajennetusta Yksinkertaiseksi (tai Yksinkertaisesta Merkki -tyyliin). "Ylös" tarkoittaa laajempaa kuvailua ja "alas" tarkoittaa tarkempaa kuvailua.
+
+Voit painaa valintaruutua, jolla voit valita, mikä navigointityyli on oletuksena, kun palautat tyylin ennalleen. Oletuksena mitään tiettyä navigointityyliä ei ole valittu.
+
+-   Navigointipuheen tyyli, kun aloitat lausekkeessa navigoimisen:
+    -   \[Puhu.\] Lukee sen kohdan matemaattisesta sisällöstä ääneen, jossa tällä hetkellä olet.
+    -   Kuvailu/anna yhteenveto. Antaa laajemman kuvailun koko valitusta sisällöstä.
+
+Voit painaa valintaruutua, jolla voit valita, nollaanko navigointipuheen tyyli, kun siirryt uuteen lausekkeeseen. Se on oletuksena valittuna.
+
+-   Puheen määrä navigoitaessa:
+    -   Harva. Tiettyjä sanoja on lyhennetty, kuten "logaritmi" on "log".
+    -   \[Keskitaso.\] Harvan ja runsaan välillä.
+    -   Runsas. Kaikki puhutaan ääneen. Luenta on yksikäsitteinen.
+
+#### Pistekirjoitus
+
+Voit valita pistekirjoitusasetukset seuraavista vaihtoehdoista. Oletusasetus on hakasuluissa.
+
+-   Matematiikan pistekirjoitus:
+    -   CMU.
+    -   Nemeth.
+    -   Ruotsalainen.
+    -   UEB.
+    -   Vietnamilainen.
+-   Korosta nykyinen navigaatiokohta pisteillä 7 ja 8:
+    -   Pois päältä.
+    -   Ensimmäinen merkki. Matemaattisen sisällön ensimmäinen merkki on korostettu.
+    -   Päätepisteet. Matemaattisen sisällön ensimmäinen ja viimeinen merkki ovat korostettuja.
+    -   Kaikki. Koko matemaattinen sisältö on korostettu.
+
+Korostus riippuu navigaatiotilan tarkkuudesta. Korostus voi olla koko matemaattisen sisällön alueella tai yksityiskohtaisempana esimerkiksi murtoluvun alussa.
+
+### Kaikki navigaatiokomennot
+
+Taulukossa on esitetty kaikki komennot, joita voit käyttää matemaattisessa sisällössä liikkumiseen. Ensimmäisessä sarakkeessa on näppäimen nimi. Toisessa sarakkeessa kerrotaan, mitä tapahtuu, jos painat vain kyseistä näppäintä. Kolmannessa sarakkeessa kerrotaan, mitä tapahtuu, jos painat näppäinkomentona Ctrl-näppäintä ja kyseistä näppäintä. Neljännessä sarakkeessa kerrotaan, mitä tapahtuu, jos painat näppäinkomentona Vaihto-näppäintä ja kyseistä näppäintä. Viidennessä sarakkeessa kerrotaan, mitä tapahtuu, jos painat näppäinkomentona Ctrl- ja Vaihto-näppäimiä ja kyseistä näppäintä.
+
+Sarakematematiikalla tarkoitetaan matemaattista sisältöä, joka esitetään taulukkona, kuten matriisit, yhtälöparit tai -ryhmät. Niitä voi navigoida kuten taulukoita.
+
+| Näppäin | Pelkästään | \+ Ctrl | \+ Vaihto | \+ Ctrl + Vaihto |
+| --- | --- | --- | --- | --- |
+| Nuoli vasen | Siirry edelliseen. | Taulukossa: siirry edelliseen soluun. Sarakematematiikassa: siirry edelliseen numeroon. Huomaa: Ctrl+Alt+Nuoli vasen toimii myös. | Lue edellinen. | Kuvaile edellinen. |
+| Nuoli oikea | Siirry seuraavaan | Taulukossa: siirry seuraavaan soluun. Sarakematematiikassa: siirry seuraavaan numeroon. Huomaa: Ctrl+Alt+Nuoli oikea toimii myös. | Lue seuraava. | Kuvaile seuraava. |
+| Nuoli ylös | Siirry yleisemmälle tasolle. | Taulukossa: siirry sarakkeessa yksi solu ylöspäin. Sarakematematiikassa: siirry sarakkeessa yksi numero ylöspäin. Huomaa: Ctrl+Alt+Nuoli ylös toimii myös. | Muuta navigointitilaa (Laajennettu, Yksinkertainen, Merkki) yleisemmäksi. | Siirry uloimmalle tasolle (uloin taso). |
+| Nuoli alas | Siirry yksityiskohtaisemmalle tasolle. | Taulukossa: siirry sarakkeessa yksi solu alaspäin. Sarakematematiikassa: siirry sarakkeessa numero alaspäin. Huomaa: Ctrl+Alt+Nuoli alas toimii myös. | Muuta navigointitilaa (Laajennettu, Yksinkertainen, Merkki) tarkemmaksi. | Siirry yksityiskohtaisimmalle tasolle (sisin taso). |
+| Enter | Missä olen. | Missä olen (globaali). |     |     |
+| Numeronäppäimet 1-10 (0 on 10) | Siirry paikkamerkkiin. | Aseta paikkamerkki. | Lue paikkamerkki. | Kuvaile paikkamerkki. |
+| Välilyönti | Lue nykyinen. | Lue nykyinen solu. | Vaihda "puhetyyliä" tyyliin lue tai kuvaile. | Kuvaile nykyinen. |
+| Home | Siirry matemaattisen sisällön alkuun. | Siirry rivin alkuun. | Taulukossa: Siirry sarakkeen alkuun. Sarakematematiikassa: Siirry sarakkeen alkuun. |     |
+| End | Siirry matemaattisen sisällön loppuun. | Siirry rivin loppuun. | Taulukossa: Siirry sarakkeen loppuun. Sarakematematiikassa: Siirry sarakkeen loppuun. |     |
+| Askelpalautin (backspace) | Siirry takaisin edelliseen sijaintiin. |     |     |     |
diff --git a/docs/users.md b/docs/users.md
@@ -1,3 +1,8 @@
+---
+layout: default
+lang: en
+ref: users
+---
 # <img src="logo.png" style="position: relative; top: 16px; z-index: -1;" alt="MathCAT logo"> User Guide
 
 ## Advice on Choosing a Voice