Hjem » Software » Komplet guide til, hvad Docusaurus er, hvad det bruges til, og hvordan det fungerer
En komplet guide til, hvad Docusaurus er, hvad det bruges til, og hvordan det fungerer
Docusaurus omdanner Markdown-filer til professionelle og dynamiske dokumentationswebsteder ved hjælp af React og MDX.
Det giver dig mulighed for at administrere versioner, internationalisering, plugins, blogs og visuel tilpasning, og tilpasse dig projekter af enhver størrelse.
Dens klare struktur, CI/CD-integration og enkle implementering har gjort den til branchestandarden for dokumentationssider i teknologisektoren.
I dag er dokumentation af teknologiprojekter blevet en essentiel søjle for succes, implementering og vedligeholdelse af software og værktøjer . Hvorfor? Opdateret, organiseret og visuelt tiltalende dokumentation gør hele forskellen mellem et projekt, der tager fart, og et, der forsvinder i glemsel. I denne sammenhæng har Docusaurus opnået sit ry som en af de mest anvendte og anerkendte statiske webstedsgeneratorer blandt udviklere, produktteams og alle, der ønsker at omdanne simple Markdown-filer til et professionelt, æstetisk tiltalende, hurtigt og letvedligeholdende websted.
Men hvad er Docusaurus egentlig? Hvis du har hørt om det, læst referencer til det hist og her, eller blot har brug for en praktisk løsning til at oprette, organisere og hoste teknisk dokumentation (eller enhver form for statisk indhold), er her den mest komplette og opdaterede guide til Docusaurus: hvordan det fungerer, hvad det bruges til, hvad der gør det specielt, og hvorfor det er det førende alternativ for tusindvis af tech-virksomheder og open source-projekter.
Docusaurus er en open source statisk hjemmesidegenerator, der konverterer Markdown- og MDX-filer til fuldt funktionelle hjemmesider med særlig fokus på detaljer i teknisk dokumentation. Dens kernemotor er bygget med React , og hele arbejdsgangen er designet til at gøre livet lettere for både avancerede udviklere og dokumentationsteams, uden nogensinde at ofre fleksibilitet og tilpasning.
Projektet startede i 2017 som et internt initiativ hos Meta (Facebook) med det klare mål at spare tid under lanceringen af dokumentationssider . Siden da har det vundet frem og er blevet de facto standarden for moderne og skalerbare dokumentationssider. Docusaurus, der er licenseret under MIT og kan prale af over 35.000 'stjerner' på GitHub, har for nylig udgivet version 2 (og nu version 3), hvilket overvinder de indledende begrænsninger og mangedobler dets potentiale for både små projekter og giganter som Microsoft eller Shopify.
Docusaurus giver dig i bund og grund mulighed for at skrive indhold i Markdown eller MDX, så du kan fokusere udelukkende på den information, du ønsker at formidle, og glemme de kedelige aspekter af implementering, visuel konfiguration og sidegenerering. Det styrer også versionskontrol og giver dig mulighed for at oprette blogs, brugerdefinerede sider og en fuldt fleksibel struktur . Dette frigør dig fra tekniske komplikationer: du håndterer indholdet, og Docusaurus tager sig af resten.
Hovedtræk ved Docusaurus
Baseret på React: Docusaurus bruger React som sin siderenderingsmotor, hvilket betyder, at du kan integrere interaktive komponenter og slippe din kreativitet løs direkte fra Markdown eller MDX.
Markdown og MDX-understøttelse: Dens motor behandler klassisk Markdown og MDX (Markdown Extended), hvilket giver dig mulighed for at blande React-komponenter og Markdown-syntaks i de samme dokumenter.
Administration af dokumentationsversioner: Det er muligt at vedligeholde flere versioner af det samme dokumentationswebsted, hvilket er ideelt til biblioteker eller produkter, der kræver visning af manualer fra forskellige udgivelser.
Internationalisering (i18n): Docusaurus har indbygget flersproget understøttelse, hvilket gør det nemmere at oversætte projekter eller samarbejde med globale teams.
Integreret søgning: Den tilbyder automatisk integration med Algolia DocSearch, en tjeneste, der bruges af internationale projekter og er en benchmark for kvalitet i effektiv lokalisering af ethvert indhold.
Temaer og tilpasning: Du kan tilpasse ethvert visuelt aspekt ved at tilsidesætte CSS-variabler eller bruge "swizzle"-systemet til at ændre specifikke komponenter. Derudover er der officielle temaer og en lang række plugins oprettet af fællesskabet.
Bloggenerator: Det giver dig mulighed for at tilføje en blog som en del af webstedet, hvilket er meget nyttigt til at vedligeholde ændringslogge, annoncere nyheder eller udgive artikler relateret til projektet.
Enkel, men udvidelig konfiguration: Al kontrol findes i en enkelt konfigurationsfil (docusaurus.config.js), hvorfra du kan justere alt fra navigationslinjen til sidefoden, inklusive plugins, tilpasninger og SEO-parametre.
Ultra-enkel implementering: Ethvert genereret websted er rent statisk, kan optimeres via CDN og implementeres på tjenester som Vercel, Netlify, GitHub Pages eller Cloudflare Pages.
Hvad adskiller Docusaurus fra andre alternativer
Det, der adskiller Docusaurus fra de fleste statiske generatorer, er dens absolutte fokus på indhold og nem tilpasning . Mens andre generatorer som Hugo, Jekyll eller Gatsby kræver mere tid og opsætning, prioriterer Docusaurus en klar struktur fra starten og minimerer friktion. Den er blevet en favorit til teknisk dokumentation fordi:
Det giver dig mulighed for tydeligt at adskille sektionerne for dokumentation, blog og brugerdefinerede statiske sider.Ideel til projekter, hvor struktur er nøglen, og orden er et must.
Sidenavigationssystemet tilpasser sig automatisk mappestrukturen, men du kan definere den manuelt, hvis du foretrækker det..
Integrationen med Git betyder, at indholdet som standard synkroniseres med repository'et.Dette er vigtigt, hvis flere personer samarbejder om det samme projekt.
Du behøver ikke en backend-server eller database; alt er statisk og derfor sikkert, hurtigt og billigt at vedligeholde.
Fællesskabet er meget aktivt, og support er garanteret, udover at have omfattende officiel dokumentation.
Docusaurus i praksis: arkitektur og indholdsorganisation
Docusaurus organiserer hovedindholdet i tre store blokke, hver med sin egen mappe i projektet:
Dokumenter: De er gemt i mappen /docsDet er her, du finder de vigtigste dokumenter i guiden, brugermanualer, vejledninger og tekniske specifikationer. Du kan skrive i Markdown eller MDX, og alt, hvad du gemmer her, vises automatisk i sidebjælken.
Blog: Blogartikler går til kataloget /blogDette modul er valgfrit, men meget nyttigt til at holde fællesskabet informeret om ændringer eller opdateringer. Hvert indlæg har sin egen fil med metadata og indhold.
Brugerdefinerede sider (Sider): inden /src/pages Du kan oprette en hvilken som helst ekstra side, lige fra en brugerdefineret hjemmeside til en "Om"-sektion eller kontaktformularer.
Disse tre sektioner kombineres med navigationsindstillingerne, versionsstrukturen og muligheden for at oversætte til flere sprog, hvilket gør det muligt at dække næsten ethvert scenarie fra starten.
Typisk mappe- og filstruktur
Når du opretter et nyt projekt med Docusaurus, er den typiske struktur ret ren:
/blog: Blogartikler eller indlæg af ændringslogtypen.
/dokumenter: Hoveddokumenter (i Markdown eller MDX).
/src/css: Brugerdefinerede stilarter til webstedet.
/src/sider: Brugerdefinerede sider i JSX, TSX eller MDX.
/statisk: Statiske filer såsom billeder, favicon, robots.txt eller andre nødvendige statiske ressourcer.
docusaurus.config.js: Global projektkonfiguration (navigationslinje, sidefod, plugins, SEO…).
sidebars.js: Valgfri struktur og eksplicit rækkefølge af dokumentationssidebjælken.
package.json: Afhængigheder og scripts, da det er et Node.js/React-projekt.
Installation og første trin med Docusaurus
Installationsprocessen for Docusaurus er meget enkel og tager kun et par minutter. Kravene er steget med de nyeste versioner og kræver mindst Node.js 16.14 til Docusaurus v2 og Node.js 20 til v3. SSG er fuldstændig flad (den kræver ingen ekstra servere eller databaser), så den er utrolig nem at bruge.
installere node.js i dit system, hvis du ikke allerede har det.
I din terminal skal du navigere til den mappe, hvor du vil oprette projektet, og starte det:
Den klassiske forudindstilling inkluderer en valgfri blog, et visuelt tema, tilpasningsmuligheder og de vigtigste funktioner.
Gå ind i mappen og start den lokale server til udvikling:
npm start
Dette åbner webstedet i din browser i udviklingstilstand med hot reload.
Når alt er klar, og du vil forberede webstedet til offentliggørelse:
npm køre build
En optimeret version vil blive genereret i build/ -mappen , klar til implementering på enhver statisk hosting.
Sådan skriver og organiserer du dokumentation i Docusaurus
Docusaurus' kerneprogram er Markdown, selvom MDX-understøttelsen siden version 2 er taget et skridt videre og tillader brugen af React i kombination med det klassiske Markdown-format. Hver dokumentfil accepterer metadata i headeren, som bestemmer titlen, identifikatoren, dens placering i sidebjælken og endda rækkefølgen, når der er flere versioner.
--- id: guia-inicial title: Indledende guide sidebar_position: 1 --- # Velkommen til din dokumentation Her kan du blande rent indhold, kodeblokke, tabeller og endda React-komponenter.
Hvert dokument konverteres automatisk til en specifik side med sin egen brugervenlige URL, sidenavigation, breadcrumbs og versioner, hvis du bruger dem.
Derudover giver Docusaurus dig mulighed for direkte at integrere interaktiv grafik med plugins som Mermaid, importere kodestykker, krydsreferere dokumenter, organisere sidebjælken automatisk eller manuelt og opdele dokumentation i logiske undermapper med deres egne genererede indeks.
Sådan tilpasser du Docusaurus: temaer, stilarter og indstillinger
Docusaurus tilbyder kraftfuld, men enkel visuel og adfærdsmæssig tilpasning. Hovedfilen til dette er docusaurus.config.js . Her kan du justere alt fra webstedets navn og slogan til navigationslinjen og sidefodsindstillingerne, samt oversættelsesparametre, SEO, integration med eksterne tjenester og avanceret plugin-konfiguration.
Basistemaet bruger Infima, et CSS-system designet til modularitet og rent design. Tilpasning af farver, skrifttyper eller enhver global variabel er så simpelt som at redigere filen /src/css/custom.css . Du kan tilsidesætte standardfarver eller tilføje dine egne regler.
For avancerede ændringer giver kommandoen "swizzle" dig mulighed for at udtrække enhver komponent i temaet for at tilpasse den efter din smag . Det er en effektiv mulighed, men brug den klogt, da visse udtrukne komponenter kræver manuel vedligeholdelse med hver Docusaurus-opdatering.
Du kan også tilføje eller fjerne navlinje- og sidefodssektioner direkte fra indstillingerne, definere eksterne links, ændre logoer, arve stilarter i henhold til mappestrukturen og endda oprette specifikke konfigurationer for webstedssektioner.
Avanceret administration: versionsstyring og oversættelser (i18n)
En af Docusaurus' styrker er dens omfattende styring af versionsstyring og flersproget support.
Versionsbaseret: Når du opretter en ny version, tager Docusaurus et "øjebliksbillede" af de aktuelle dokumenter og kopierer dem til en intern mappe. versioneret_dokumentation/På denne måde kan du holde den gamle dokumentation i live, ideelt til API'er, biblioteker eller frameworks, hvor ikke alle brugere opdaterer til den nyeste version.
Internationalisering: For globale projekter er oversættelse til flere sprog enkel takket være dens system af i18nDu kan integrere værktøjer som f.eks. Claude Science eller behandl oversættelsesfilerne manuelt efter dine behov.
Derudover tillader Docusaurus sidebjælken og menuerne automatisk at generere links til hver tilgængelig version og sprog, så ingen brugere farer vild.
Søg i dokumentationen: Integration med Algolia DocSearch
Docusaurus integrerer DocSearch, søgemaskinen drevet af Algolia og brugt af tusindvis af tekniske websteder verden over. Det er gratis, så længe din dokumentation er offentlig, men du kan også selv hoste en crawler, hvis du har brug for privatliv eller intern dokumentation. Konfigurationen findes i themeConfig- sektionen af docusaurus.config.js.
Brugeroplevelsen forbedres drastisk med Algolias øjeblikkelige søgning, som også kan kombineres med avancerede funktioner såsom konversationssøgning ved hjælp af AskAI.
Plugins, udvidelser og fællesskab
Docusaurus-økosystemet vokser hurtigt og har et meget aktivt fællesskab, der udvikler plugins og udvidelser.
Plugins til generering af sitemapSEO, PWA, Google Analytics, brugerdefinerede omdirigeringer eller integration med automatiske indholdsfortegnelser.
Understøttelse af avancerede diagrammer og diagrammer (Mermaid, PlantUML osv.).
Integration med CI/CD-systemer til automatisk udrulning til statisk hosting efter hvert push.
Officiel support og et væld af eksempler i projektdokumentationen gør det nemt at løse eventuelle spørgsmål hurtigt, og der er en Discord-server, fora og aktive GitHub-problemer. Hvis du har brug for inspiration, kan du udforske eksempelsider genereret på den officielle Docusaurus -hjemmeside.
Implementering: Sådan publicerer du dit websted med Docusaurus
Implementering af et Docusaurus-websted er hurtigt, enkelt og alsidigt. Bygget genererer en mappe /build med den endelige HTML, CSS og JS, klar til at blive hostet, hvor du vil.
Netlify, Vercel, GitHub Pages, Cloudflare Pages og de fleste statiske løsninger fungerer uden yderligere konfiguration.
Du skal blot konfigurere udbyderen til at betjene index.html på ukendte ruter, hvilket garanterer routing via React.
For implementeringer med Kinsta muliggør panelet integration med Git-repositories, hvilket muliggør en automatisk arbejdsgang hver gang du opdaterer dokumentationens kildekode.
Docusaurus er ekstraordinært effektiv på store websteder, fordi alt indhold kan caches på CDN-niveau, og ressourceforbruget er minimalt.
Nogle almindelige anvendelser og succeshistorier
Docusaurus er ikke kun populært blandt individuelle udviklere. Store virksomheder som Microsoft, Shopify, LinkedIn og SAP bruger dette værktøj til at vedligeholde dokumentation for deres produkter, API'er og biblioteker. Du kan finde lister over rigtige (og meget inspirerende) websteder online.
Dens fleksibilitet gør den velegnet til intern virksomhedsdokumentation, såvel som Open Source-projekter, SaaS-produkter, biblioteker, frameworks, tekniske blogs og meget mere.
Vigtige forskelle mellem Docusaurus v1, v2 og v3
Over tid har Docusaurus udviklet sig betydeligt. Forskellene mellem den første og anden version er mærkbare:
v1: Den genererede simple statiske hjemmesider (ikke SPA'er), ideel til maksimal kompatibilitet, men med færre tilpasningsmuligheder. Bruges i vid udstrækning af virksomheder, der har brug for understøttelse af ældre browsere (f.eks. IE11).
v2: Den anvender en SPA-arkitektur, der følger JAMstack-filosofien, integrerer MDX og giver mulighed for langt mere fleksible websteder, landingssider, blogs, søgning, temaer, versionskontrol og avanceret SEO. Den understøtter dog ikke IE11.
v3: Forbedrer integrationen med MDX v3, forfiner plugin-systemet, tilføjer udvidet understøttelse af tematilpasninger, optimerer versionsstyring yderligere og omfavner moderne CI/CI (kræver Node 20+).
Bortset fra i meget specifikke tilfælde anbefales det altid at starte med Docusaurus v3 for at udnytte den større stabilitet og vækstkapacitet.
Alternativer til Docusaurus
Selvom Docusaurus er førende inden for dokumentation, findes der alternative projekter som Hugo, Jekyll, Gatsby, MkDocs og andre statiske billedgeneratorer såsom VuePress. Det, der har gjort Docusaurus så berømt, er dog dens blanding af enkelhed, kraft, skalerbarhed og direkte tilpasning fra Markdown/MDX med React.
Punkter at overveje, før du bruger Docusaurus
Du behøver ikke at være React-ekspert for at komme i gang: Du kan opnå de fleste konfigurationer og organisere dokumenter uden at røre en eneste linje i React.
Perfekt til dem, der foretrækker at gemme dokumentation sammen med kodearkivet: Det letter gennemgange, ændringskontrol og automatiske implementeringer.
Skalerbarhed er sikret selv på meget store websteder, selvom du muligvis har brug for mere avanceret CI/CD og smart caching til megaprojekter.
Springet fra v2 til v3 kræver en del gennemgang, især hvis du har brugt brugerdefinerede React-komponenter i dine gamle MDX-projekter.Den nye parser er strengere og hjælper med at opdage reelle JSX-fejl, der tidligere ikke blev bemærket.
For avancerede spørgsmål tilbyder den officielle hjemmeside oversat dokumentation og detaljerede forklaringer for både begyndere og eksperter:
Dens nemme implementering, native integration med søgning, analyse og CI/CD-plugins samt muligheden for at skalere fra en lille guide til en hel virksomhedshjemmeside gør Docusaurus til en af de bedste muligheder for at omdanne de tekniske oplysninger om ethvert projekt eller produkt til en tilgængelig, visuelt tiltalende og nyttig ressource for både nybegyndere og avancerede udviklere.
