ITDD Kursusinfrastruktur¶

Den korte version¶

Vi redigerer kursusmateriale i Docmost – et kollaborativt wiki-værktøj. Når vi er klar til at publicere, kører vi ét script, som automatisk opdaterer det offentlige kursuswebsted på courses.itdd.au.dk.

De tre lag¶

1. Docmost – vores arbejdsplads¶

Docmost er det sted, vi skriver og redigerer kursusmateriale. Det fungerer som et fælles notesbog: flere undervisere kan arbejde i samme dokument på samme tid, kommentere, foreslå ændringer og organisere indhold i et sidehierarki.

Docmost er ikke det offentlige kursuswebsted. Det er vores bagside – et arbejdsrum.

2. GitLab – vores arkiv¶

GitLab er et versionsstyringssystem. Det gemmer alle versioner af kursusmaterialet og fungerer som den officielle "kilde til sandhed" (single source of truth).

Hvis noget går galt – en tekst slettes ved en fejl, en ændring fortryder sig selv – kan vi altid gå tilbage til en tidligere version. GitLab er vores sikkerhedsnet.

3. MkDocs – det offentlige kursuswebsted¶

courses.itdd.au.dk er det studerende ser. Webstedet er bygget med MkDocs, et system der omdanner vores tekstfiler til et pænt, søgbart website. Det opdateres ikke automatisk – det kræver, at vi aktivt publicerer.

Arbejdsflowet i praksis¶

Undervisere redigerer i Docmost
           ↓
    Klar til publicering?
           ↓
   Kør synkroniseringsscriptet
           ↓
  Ændringerne sendes til GitLab
           ↓
  GitLab bygger og publicerer
  automatisk til webstedet

I dag kører synkroniseringen halvmanuelt: vi eksporterer fra Docmost og kører et script lokalt. Det tager få minutter.

På sigt vil vi koble det tættere sammen, så der fx er en "Publicér"-knap direkte i Docmost.

Hvad synkroniseringsscriptet gør¶

Scriptet oversætter automatisk fra Docmosts format til MkDocs' format:

Tekstbokse (advarsler, info-kasser osv.) konverteres til MkDocs' tilsvarende format
Interne links mellem sider opdateres, så de peger rigtigt
Filnavne renses for specialtegn og mellemrum
Billeder hentes og gemmes i kursusmapperne

Billeder – en vigtig detalje¶

Billeder, der uploades direkte i Docmost, gemmes i Docmosts interne lager og kan ikke exporteres automatisk. Billeder der skal fungere på begge platforme skal ligge ét af disse steder:

SharePoint/OneDrive: indsæt som eksternt link (fungerer i både Docmost og på webstedet)
GitLab-repoen: gem billedet i docs/<kursus>/assets/ – referér til det med den fulde URL på webstedet (https://courses.itdd.au.dk/<kursus>/assets/billede.png) i Docmost

Hvorfor ikke bare bruge Docmost som websted?¶

Det kunne man i princippet. Men:

GitLab giver os versionsstyring og backup – vi kan altid rulle tilbage
MkDocs-webstedet er hurtigere, kan tilpasses mere og kræver ikke login for studerende
Docmost forbliver et lukket arbejdsrum for undervisere; det offentlige websted er adskilt

Spørgsmål?¶

Kontakt Francesco Caviglia (caviglia@edu.au.dk) eller Niels Kristian Beck (nbeck@edu.au.dk).