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:

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:

cd /Users/nico/skillstown

Installeer vervolgens de benodigde pakketten:

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:

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:

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:

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:

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:

{
  "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

/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:

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

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:

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:

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