markdown_to_skillstown/GEBRUIKSHANDLEIDING-IMPORT.md

# Gebruikershandleiding Import Naar OnlineAcademy

Deze handleiding beschrijft een eenvoudige en vaste werkwijze voor het aanleveren en importeren van een training op basis van markdown.

Het doel is dat je per training altijd dezelfde structuur gebruikt, zodat je niet hoeft te onthouden:

- waar bestanden moeten staan
- hoe afbeeldingen gekoppeld worden
- waar de URL moet worden ingevuld
- hoe je eerst een controle uitvoert en daarna pas de echte import start

## 1. Wat moet ik op macOS installeren?

Om de robotisering te gebruiken heb je op macOS het volgende nodig:

- Terminal
- Node.js
- npm
- de projectmap `/Users/nico/skillstown`

### Node.js installeren

Controleer eerst of Node.js al aanwezig is:

```bash
node -v
npm -v
```

Als beide opdrachten een versienummer tonen, dan is Node.js al goed geïnstalleerd.

Als dat niet zo is, installeer dan:

1. Node.js LTS via de officiële website
2. daarna opnieuw controleren met `node -v` en `npm -v`

Praktisch minimum:

- gebruik een recente LTS-versie van Node.js

### Playwright-dependencies installeren

Ga daarna in Terminal naar de projectmap:

```bash
cd /Users/nico/skillstown
```

Installeer vervolgens de benodigde pakketten:

```bash
npm install
```

Als dit klaar is, is de lokale omgeving gereed.

## 2. Waar zet ik mijn OnlineAcademy login neer?

De runner heeft twee inloggegevens nodig:

- `OA_EMAIL`
- `OA_PASSWORD`

Zet deze in een lokaal `.env` bestand in de projectmap:

`/Users/nico/skillstown/.env`

Voorbeeld:

```dotenv
OA_EMAIL=jouw.email@voorbeeld.nl
OA_PASSWORD=jouwWachtwoordHier
```

Belangrijk:

- het bestand heet precies `.env`
- het staat in de hoofdmap van het project
- zonder dit bestand kan de runner niet inloggen

### Moet ik `.env` nog handmatig laden?

Nee, dat hoeft niet meer als je `--env-file` gebruikt.

De runner kan het `.env` bestand zelf inlezen.

Gebruik dus gewoon:

```bash
cd /Users/nico/skillstown
node onlineacademy-playwright-runner.mjs \
  --training-dir trainings/intro-sql \
  --env-file .env
```

Alleen als je geen `--env-file` gebruikt, moet je nog handmatig variabelen laden.

Als de runner geen credentials kan vinden, krijg je een foutmelding zoals:

`Zet OA_EMAIL en OA_PASSWORD in .env of in de omgeving.`

## 3. Waar maak ik de map aan?

Maak de trainingsmap altijd aan in deze hoofdmap:

`/Users/nico/skillstown/trainings/`

Elke training krijgt daar een eigen submap.

Voorbeeld:

- `/Users/nico/skillstown/trainings/sql-basics-01/`
- `/Users/nico/skillstown/trainings/excel-gevorderd/`
- `/Users/nico/skillstown/trainings/pilot-hoofdstuk-04/`

Gebruik bij voorkeur een korte en herkenbare mapnaam, zonder rare tekens.

Aanbevolen stijl:

- alleen kleine letters
- woorden gescheiden met `-`

Voorbeeld:

`/Users/nico/skillstown/trainings/intro-sql/`

## 4. Welke bestanden moeten daarin staan?

Elke trainingsmap bevat precies deze onderdelen:

- `content.md`
- `training.json`
- `assets/`

De structuur is dus:

```text
trainings/
  intro-sql/
    content.md
    training.json
    assets/
```

## 5. Wat is `content.md`?

`content.md` is het hoofdbestand met de inhoud van de training.

Hierin staat:

- hoofdstukken
- pagina's
- tekstblokken
- vragen
- tabellen
- verwijzingen naar afbeeldingen

De afspraak is:

- de inhoud staat altijd in `content.md`
- de bestandsnaam is dus niet vrij, maar vast

Dat voorkomt verwarring.

## 6. Wat is `assets/`?

`assets/` is de map voor alle bijbehorende bestanden die vanuit de markdown nodig zijn.

Denk aan:

- afbeeldingen
- screenshots
- illustraties

Dus:

- `assets/` is geen apart systeemonderdeel
- het is gewoon een submap binnen de trainingsmap

Voorbeeld:

```text
trainings/
  intro-sql/
    content.md
    training.json
    assets/
      query-voorbeeld.png
      joins-overzicht.png
      database-schema.jpg
```

## 7. Hoe verwijs ik in de markdown naar bestanden in `assets/`?

Gebruik in de markdown altijd relatieve paden vanaf `content.md`.

Dus verwijs naar bestanden als:

- `assets/query-voorbeeld.png`
- `assets/joins-overzicht.png`

Niet doen:

- absolute paden zoals `/Users/nico/...`
- bestanden buiten de trainingsmap

De werkafspraak is:

- alles wat de training nodig heeft staat in de eigen trainingsmap
- alle afbeeldingen staan in `assets/`

## 8. Wat is `training.json`?

`training.json` is het configuratiebestand van die ene training.

Daarin staat niet de inhoud, maar alleen de instellingen die nodig zijn om de import te draaien.

De belangrijkste instelling is:

- de OnlineAcademy edit-URL

`training.json` staat dus hier:

`/Users/nico/skillstown/trainings/<naam-van-de-training>/training.json`

Voorbeeld:

`/Users/nico/skillstown/trainings/intro-sql/training.json`

## 9. Wat zet ik in `training.json`?

Minimaal alleen de URL.

Voorbeeld:

```json
{
  "url": "https://create.onlineacademy.nl/.../edit?idsVersion=6"
}
```

Je hoeft hier dus geen markdown of afbeeldingen in te zetten. Alleen de doel-URL van de training.

## 10. Volledig voorbeeld van een trainingsmap

```text
/Users/nico/skillstown/trainings/intro-sql/
  content.md
  training.json
  assets/
    query-voorbeeld.png
    joins-overzicht.png
```

Met:

- `content.md` voor de inhoud
- `training.json` voor de URL
- `assets/` voor de afbeeldingen

## 11. Hoe start ik de import?

De import start je vanuit de terminal, in de hoofdmap van het project:

`/Users/nico/skillstown`

Je hoeft dus niet op een knop te drukken. De import wordt gestart met één commando.

Er zijn twee modi:

- reviewmodus
- uitvoermodus

Binnen de uitvoermodus zijn er twee varianten:

- uitvoeren zonder opslaan
- uitvoeren en daarna `Opslaan als` klikken

## 12. Hoe start ik alleen de reviewmodus?

Gebruik reviewmodus om eerst te controleren of:

- het `.env` bestand gevonden wordt
- de login werkt
- de juiste training wordt geopend
- de markdown kan worden gelezen
- de afbeeldingen gevonden worden
- de structuur logisch is

Commando:

```bash
node onlineacademy-playwright-runner.mjs \
  --training-dir trainings/intro-sql \
  --env-file .env
```

Wat gebeurt er in reviewmodus:

- de browser opent
- er wordt ingelogd
- de URL wordt automatisch uit `training.json` gelezen
- de doelpagina wordt geopend
- er wordt een controle uitgevoerd
- er worden screenshots en controlegegevens opgeslagen
- er worden nog geen muterende importacties uitgevoerd

Belangrijk:

- zonder `--execute` blijft de runner in reviewmodus

## 13. Hoe start ik de echte import?

Als de review goed is, start je dezelfde opdracht opnieuw, maar dan met `--execute`.

### Variant A: uitvoeren zonder opslaan

```bash
node onlineacademy-playwright-runner.mjs \
  --training-dir trainings/intro-sql \
  --env-file .env \
  --execute
```

Wat gebeurt er dan:

- de browser opent
- de training wordt geopend
- pagina's en blokken worden in de editor opgebouwd
- de runner vult de inhoud in op basis van `content.md`
- de runner stopt daarna op het reviewpunt
- het scherm blijft open zodat je kunt controleren wat er is ingevoerd
- de inhoud is nog niet opgeslagen

### Variant B: uitvoeren en daarna opslaan

Gebruik hiervoor de extra flag `--save`.

Commando:

```bash
node onlineacademy-playwright-runner.mjs \
  --training-dir trainings/intro-sql \
  --env-file .env \
  --execute \
  --save
```

Wat gebeurt er dan:

- de browser opent
- de training wordt geopend
- pagina's en blokken worden in de editor opgebouwd
- de runner vult de inhoud in op basis van `content.md`
- de runner klikt daarna op de knop `Opslaan als`
- de runner kiest daarna in de popup de optie `Concept`

## 14. Hoe weet ik of de review goed is?

De review is goed als:

- de juiste OnlineAcademy-training opent
- de runner zonder foutmelding door de controle komt
- de screenshots laten zien dat je in de editor zit
- de markdown en assets correct gevonden zijn

Je hoeft dus niet technisch te beoordelen wat er intern gebeurt. Je kijkt vooral naar:

- opent de juiste training
- zie ik de editor
- ontbreken er geen bestanden
- krijg ik geen foutmelding

## 15. Hoe weet ik wat ik moet verbeteren als de review niet goed is?

Als de review niet goed is, kijk je eerst naar vier dingen:

1. Bevat `.env` de velden `OA_EMAIL` en `OA_PASSWORD`?
2. Klopt de URL in `training.json`?
3. Bestaat `content.md` echt in de trainingsmap?
4. Bestaan alle bestanden in `assets/` waarnaar de markdown verwijst?

De meest voorkomende oorzaken zijn:

- `.env` ontbreekt
- `OA_EMAIL` of `OA_PASSWORD` ontbreekt
- verkeerde URL
- typefout in bestandsnaam
- afbeelding staat niet in `assets/`
- markdown verwijst naar een bestand dat niet bestaat
- inhoud gebruikt een bloktype dat nog niet ondersteund is

Praktische werkwijze:

1. Lees de foutmelding.
2. Controleer de trainingsmap.
3. Controleer `.env`.
4. Corrigeer `content.md`, `training.json` of `assets/`.
5. Start opnieuw in reviewmodus.
6. Pas als de review goed is, draai je `--execute`.

## 16. Waar vind ik de controlebestanden en screenshots terug?

De runner slaat resultaten op in `artifacts/`.

Daar vind je onder andere:

- screenshots
- plan-overzicht
- validatie-uitvoer
- foutstatus bij mislukte runs

Dat helpt om achteraf te zien:

- wat er geopend is
- hoe ver de runner kwam
- waar het mogelijk misging

## 17. Welke uitvoer zie ik in de terminal?

De runner geeft tijdens een run korte voortgangsmeldingen, bijvoorbeeld:

- `[STAP] Voorbereiden`
- `[STAP] Browser openen`
- `[STAP] Inloggen`
- `[STAP] Editor controleren`
- `[STAP] Inhoud opbouwen`
- `[INFO] Hoofdstuk 1 van 1: ...`
- `[INFO] Pagina 3 van 8: ...`
- `[INFO] Blok 2 van 4: image - ...`
- `[STAP] Resultaat`

Bij een geslaagde execute-run zie je nu:

- `Execute-run afgerond tot het reviewpunt.`
- `De inhoud is opgebouwd in de editor.`
- `Er is nog niet opgeslagen.`

Dat betekent:

- de invoer is uitgevoerd
- de inhoud staat in de editor
- de inhoud is nog niet definitief bewaard in OnlineAcademy

Bij een execute-run met `--save` zie je:

- `Execute-run afgerond.`
- `De runner heeft op 'Opslaan als' geklikt en daarna 'Concept' gekozen.`

Dat betekent:

- de invoer is uitgevoerd
- de runner heeft de save-flow bediend
- je moet in de browser nog controleren of OnlineAcademy die actie zichtbaar bevestigt

## 18. Aanbevolen vaste werkwijze per training

Gebruik steeds deze volgorde:

1. Installeer Node.js en voer `npm install` uit.
2. Maak `.env` aan in `/Users/nico/skillstown/`.
3. Maak een map aan in `trainings/`.
4. Zet de inhoud in `content.md`.
5. Zet alle afbeeldingen in `assets/`.
6. Zet de doel-URL in `training.json`.
7. Start eerst de reviewmodus met `--training-dir` en `--env-file`.
8. Controleer of de juiste training opent en of er geen fouten zijn.
9. Start daarna de uitvoermodus met `--execute`.
10. Voeg `--save` alleen toe als de runner ook echt op `Opslaan als` moet klikken.

## 19. Samenvatting

De vaste afspraak is:

- Node.js en `npm install` zijn vooraf geregeld
- inloggegevens staan in `.env`
- elke training staat in een eigen map onder `trainings/`
- de inhoud staat in `content.md`
- de URL staat in `training.json`
- de afbeeldingen staan in `assets/`
- eerst review draaien met `--training-dir` en `--env-file`
- daarna pas `--execute`
- voeg alleen `--save` toe als de runner aan het eind op `Opslaan als` moet klikken

De standaardstructuur is:

```text
/Users/nico/skillstown/trainings/<trainingsnaam>/
  content.md
  training.json
  assets/
```