Look Scanned How-To dokumentasie na VitePress migreer met verbeterde sekuriteit

By Look Scanned verbeter ons voortdurend ons infrastruktuur om beter dokumentasie en veiliger ontwikkelingspraktyke te verskaf. Vandag is ons opgewonde om besonderhede te deel oor ‘n beduidende opgradering van ons How-To dokumentasiewebwerf: die migrasie van ‘n pasgemaakte Vue + Vite-toepassing na VitePress, terwyl ons terselfdertyd ons CI/CD-sekuriteit met npm Trusted Publishers verbeter.

📚 Hoekom ons na VitePress gemigreer het

Ons How-To dokumentasiewebwerf (github.com/lookscanned/how-to) dien as die omvattende gebruiksgids vir Look Scanned. Alhoewel ons vorige Vue + Vite-opstelling goed gewerk het, het ons besef dat VitePress ‘n beter keuse sou wees vir ‘n inhoud-gedrewe dokumentasiewebwerf.

Wat is VitePress?

VitePress is ‘n statiese werf-generator wat spesifiek vir dokumentasie ontwerp is. Gebou bo-op Vite en Vue 3, kombineer dit die beste van beide wêrelde: weerlig-vinnige ontwikkelingservaring met kragtige dokumentasie-funksies uit die boks.

Sleutelvoordele van die migrasie

🎯 Beter argitektuur vir dokumentasie

Lêer-gebaseerde roetevorming: Elke markdown-lêer word outomaties ‘n bladsy, wat inhoud-organisasie intuïtief maak
Ingeboude dokumentasie-funksies: Inhoudsopgawe, soektog, internasionalisering, en meer kom vooraf gekonfigureer
Statiese werf-generasie: Vooraf-gerenderde HTML bied uitstekende SEO en kitssig bladsy-ladings

⚡ Verbeterde ontwikkelaarservaring

Kitssig warm herlaai: Veranderinge verskyn onmiddellik tydens ontwikkeling
Markdown eerste: Fokus op inhoud, nie op komponent-steierwerk nie
Vue-komponent ondersteuning: Wanneer nodig, kan ons steeds pasgemaakte Vue-komponente binne markdown gebruik

🔧 Makliker onderhoud

Duideliker struktuur: Dokumentasie volg konvensies, wat kognitiewe las vir bydraers verminder
Meer stabiele bous: VitePress se geopinieerde struktuur lei tot meer reproduseerbare bous
Beter samewerking: Spanlede kan bydra tot dokumentasie sonder diep Vue-kennis

🔒 Verbeterde sekuriteit met npm Trusted Publishers

Saam met die VitePress-migrasie het ons ‘n kritieke sekuriteitsverbetering geïmplementeer: npm Trusted Publishers met behulp van OIDC-verifikasie.

Die probleem met tradisionele npm-tokens

Voorheen het die publisering van pakkette na npm vereis dat ‘n langdurige NPM_TOKEN in repository-geheime gestoor word. Hierdie benadering het verskeie nadele:

Sekuriteitsrisiko: Tokens kan per ongeluk blootgestel of gekompromitteer word
Bestuursoorghoof: Tokens benodig handmatige rotasie en opdaterings
Oudit-uitdagings: Moeilik om by te hou wie wat wanneer gepubliseer het

Die oplossing: OIDC-gebaseerde betroubare publisering

npm Trusted Publishers benut OpenID Connect (OIDC) om veilige, token-vrye publisering direk vanaf GitHub Actions moontlik te maak. Hier is hoe dit werk:

Geen gestoorde geheime nie: In plaas van om tokens te stoor, versoek GitHub Actions kortdurige geloofsbriewe by npm
Identiteitsverifikasie: npm verifieer dat die publiseringsversoek van die gemagtigde GitHub-bewaarplek gekom het
Outomatiese geloofsbriewe-bestuur: Geloofsbriewe word outomaties uitgereik en verval vinnig

Werklike wêreld voordele

Hierdie verandering bring onmiddellike verbeteringe na ons ontwikkelingswerkstroom:

✅ Geen token-bestuur meer nie: Geen behoefte om npm-tokens te skep, te stoor of te roteer nie
✅ Verminderde aanvalsoppervlak: Kortdurige geloofsbriewe minimaliseer blootstellingsrisiko
✅ Beter ouditbaarheid: Elke publiseringsaksie is gekoppel aan ‘n spesifieke GitHub Actions-lopie
✅ Moderne beste praktyke: Belyn met zero-trust sekuriteitsbeginsels

Tegniese nota: Om npm Trusted Publishers te ondersteun, het ons ons CI-konfigurasie opgedateer om Node.js lts/* te gebruik, wat verseker dat ons die nuutste npm-weergawe het wat vir OIDC-verifikasie vereis word.

📦 Vrystellings-tydlyn

Die migrasie is voltooi deur drie vrystellings op 19 Desember 2025:

v2.0.0: Kern-migrasie van Vue + Vite na VitePress (brekende verandering)
v2.0.1: CI-regstelling om npm Trusted Publishers met behoorlike Node.js-weergawe te ondersteun
v2.0.2: Prestasieverbetering deur @fontsource/noto-mono na devDependencies te skuif

🌍 Voortgesette meertalige ondersteuning

‘n Belangrike nota: ons How-To dokumentasie genereer meertalige PDF’s wat altyd as voorbeeldlêers in die hoof Look Scanned-toepassing gebruik is (beskikbaar by lookscanned.io/en/scan). Hierdie VitePress-migrasie verander nie daardie funksionaliteit nie—dit verskaf bloot ‘n beter grondslag vir die instandhouding en verbetering van ons dokumentasie-infrastruktuur.

💡 Wat dit vir gebruikers beteken

As jy Look Scanned se dokumentasie gebruik:

Dieselfde toegang, beter ervaring: Dokumentasie bly by dieselfde URL met verbeterde laai en navigasie
Meer betroubaar: Statiese werf-generasie beteken vinniger ladings en beter stabiliteit
Beter soek en ontdekking: VitePress se ingeboude soektog help jou om vinniger antwoorde te vind
Voortgesette PDF-ondersteuning: Meertalige PDF-generasie gaan voort soos voorheen

🚀 Wat kom volgende

Met die infrastruktuur-opgradering voltooi, fokus ons op inhoudsverbeteringe:

Uitgebreide gebruiksgevalle: Meer praktiese voorbeelde en stap-vir-stap gidse
Konsekwentheidsverbeteringe: Verfyning van meertalige terminologie vir duidelikheid
Verbeterde PDF-uitvoer: Verbetering van kruis-blaaier PDF-generasie-ervaring

Probeer Look Scanned vandag

Look Scanned bied blaaier-gebaseerde, privaatheid-eerste PDF-skandeer-effekte sonder om jou lêers êrens op te laai. Die verbeterde dokumentasie maak dit makliker as ooit om te begin.

👉 Besoek lookscanned.io om vinnige, veilige dokument-skandering in jou blaaier te ervaar.