Til lette websteder, applikationer og andre små projekter bruger flere og flere udviklere statiske webstedsgeneratorer frem for WordPress eller andre content management systemer (CMS’er) til at lave lette websteder, applikationer og andre små projekter. Statiske websteder er en enkel og effektiv måde at oprette websteder og applikationer på, som er hurtige, sikre og nemme at vedligeholde.

Docusaurus er en sådan statisk site generator – og den vinder hurtigt popularitet i udviklingsmiljøet.

Træt af træge content management systemer? Mød Docusaurus! En statisk webstedsgenerator, der får jobbet gjort uden at bremse dig. Læs videre for at lære mere ✅Klik for at Tweete

I dette indlæg tager vi et dybt dyk ned i fordelene ved at bruge Docusaurs som din statiske site-generator, og hvorfor det er en voksende favorit blandt udviklere.

Hvad er Docusaurus?

Docusaurus er en populær statisk sidegenerator, der bruger React, et af de bedste JavaScript-biblioteker, som UI-bibliotek til oprettelse af sider. Ligesom andre lignende generatorer er den nem at opsætte og nem at ændre, og – vigtigst af alt – den giver dig alt, hvad du behøver for at komme i gang med dit statiske websted.

Det, der adskiller Docusaurus fra andre, er imidlertid, at det hjælper dig med at oprette og administrere et websted, hvor indhold spiller en central rolle. Det giver dig mulighed for hurtigt og nemt at opbygge et komplet websted – komplet med en blogfunktion – der sætter fokus på dit indhold fra starten.

Fordi indholdet er i fokus med Docusaurus, er det perfekt til at oprette dokumentationswebsteder som wikier. Den anvender også markdown, som er ideel både til samarbejde og lagring i et git-repository. Desuden har den et væld af fantastiske funktioner som i18n, søgning og brugerdefinerede temaer, som vi vil diskutere mere detaljeret senere.

Her er blot nogle få af de fremtrædende funktioner, der gør Docusaurus til en solid mulighed:

  • Bygget ved hjælp af React
  • Understøttelse af MDX v1
  • Støtte til indlejring af React-komponenter via Markdown
  • Versionering af dokumenter
  • Kompatibilitet med Git, Crowdin og andre oversættelsesadministratorer til oversættelse af dokumenter og bulk- eller individuel udrulning

Hvem bruger Docusaurus?

Docusaurus blev skabt af Facebook, så det er ikke overraskende, at det i øjeblikket bruges af mange store brands og virksomheder på hele nettet.

Her er blot nogle få af de største brands, der bruger Docusaurus i dag (og flere vil snart komme til, efterhånden som Docusaurus’ popularitet fortsætter med at vokse):

Og der kommer flere til hver dag.

Sådan installeres Docusaurus

Docusaurus er meget enkel at installere og tager kun et par minutter. I denne vejledning vil vi bygge et dokumentationswebsted med en blog, og vi vil tilpasse, hvordan webstedet ser ud.

Og her er den fedeste del: Det vil tage os mindre end en time at starte det hele op.

Lad os springe ud i det!

Krav

Docusarus kræver Node.js 16.14 eller nyere. Det er en flat-file SSG, hvilket betyder at du ikke har brug for en ekstra database.

Hvis du ikke allerede har Node.js 16.14+ til rådighed, skal du begynde med at installere Node.js eller opgradere din nuværende version. Derefter kan du gå videre til Docusaurus-installationsprocessen nedenfor.

Vi vil også bruge Docusaurus-eksempelwebstedet fra dette GitHub-repository. Du kan bruge den eller en ren installation af Docusaurus til denne vejledning.

Installationsproces

For at begynde Docusaurus-installationsprocessen skal du først køre følgende kommando:

npx create-docusaurus@latest  classic

Dette vil oprette en mappe for dit projekt og stilladsere det klassiske tema i den. Det klassiske tema indeholder allerede nogle forudkonfigurerede funktioner som f.eks. en blog, brugerdefinerede sider og et CSS-framework.

Efter installationen skal du derefter køre følgende kommando for at starte den lokale server:

npm start

Hvis du ønsker at opbygge en optimeret version, der er klar til udrulning, skal du køre denne i stedet:

npm run build

Struktur

Når du har installeret din Docusaurus-instans, vil du kunne åbne din projektmappe og se nærmere på “skelettet” af dit nye websted.

Her er hvordan filstrukturen ser ud:

my-website
├── blog
│ ├── 2019-05-28-hola.md
│ └── 2020-05-30-welcome.md
├── docs
│ ├── doc1.md
│ └── mdx.md
├── src
│ ├── css
│ │ └── custom.css
│ └── pages
│ ├── styles.module.css
│ └── index.js
├── static
│ └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

Der er nogle få detaljer, der skal bemærkes vedrørende nogle af disse filer og mapper:

  • /blog: Indeholder alle de filer, der er relateret til din blog.
  • /docs: Indeholder alle filer relateret til dine dokumenter. Du kan tilpasse deres rækkefølge i filen sidebar.js.
  • /src: Indeholder alle ikke-dokumentationsfiler som f.eks. sider eller brugerdefinerede komponenter.
  • /src/pages: Alle JSX/TSX/MDX-filer vil blive omdannet til sider.
  • /static: Statiske filer, der kopieres til den endelige build-mappe.
  • docusaurus.config.js: Docusaurus konfigurationsfil.
  • packaged.json: Hvert Docusaurus-websted er en React-app, så her finder du alle de afhængigheder og scripts, som det bruger til React.
  • sidebar.js: Her kan du angive rækkefølgen af dokumenter i sidebaren.

Tilpasning af din Docusaurus-installation

Som du kan se af den enkle filstruktur, er Docusaurus let at bruge og navigere. Ligeledes er det en leg at tilpasse dit Docusaurus-websted. Du kan åbne og redigere disse filer ved hjælp af din foretrukne teksteditor eller IDE.

Lad os gennemgå nogle af de tilpasningsmuligheder, du har lige ud af boksen.

Hjemmeside

Det første, du sikkert vil være ivrig efter at gøre, er at tilpasse standardhjemmesiden, så den i stedet viser dit eget projekt. Heldigvis er det ikke kompliceret at foretage de ændringer du ønsker på Docusaurus’ hjemmeside.

For at ændre hjemmesiden skal du åbne filen src/pages/index.js og foretage justeringer lige derinde. Det er en typisk React-side, så du kan ændre eller ombygge den ved at ændre indholdet eller oprette brugerdefinerede React-komponenter.

Konfigurationsfil

Dernæst dykker vi ned i den vigtige fil docusaurus.config.js og ændrer nogle vigtige detaljer for vores instans.

Navn og beskrivelse

I konfigurationsfilen finder du følgende:

const config = {
title: 'My Site',
tagline: 'Dinosaurs are cool',
url: 'https://your-docusaurus-site.com',
baseUrl: '/',

Du skal blot ændre disse detaljer, så de passer til dit websted, og derefter gemme filen.

Navigationslinje

For at redigere din navigationslinje skal du finde navbar elementet.

I vores eksempel her ønsker vi at tilføje et link til Kinsta, omdøbe punktet “Tutorial” til “Starter documentation” og tilføje Kinsta-logoet.

Her er hvordan vi ville gå til værks:

navbar: {
  title: 'Kinsta starters',
  logo: {  
    alt: 'Kinsta Logo',
    src: 'img/kinsta-logo-alpha-purple.png',
  },
  items: [
    {
      label: 'Kinsta starters',
      to: '/docs/intro',
    },
    {to: '/blog', label: 'Blog', position: 'left'},
    {
      href: 'https://github.com/kinsta',
      label: 'GitHub',
      position: 'right',
    },
  ],
},

Footer

Tilpasning af footereen i Docusaurus består af to sektioner: selve indholdet i footeren og links i footeren.

Indhold i sidefoden

Hovedparten af dit footer-indhold (ikke inklusive links-listen) kan placeres i din themeConfig.footer-fil. Dette er det ideelle sted at tilføje et logo og en copyright-meddelelse.

Her er hvordan vi har ændret vores footerkonfiguration:

module.exports = {
  themeConfig: {
    footer: {
      logo: {
        alt: 'Kinsta Logo',
        src: 'img/kinsta-logo.png',
        href: 'https://kinsta.com',
        width: 160,
        height: 51,
      },
      copyright: `Copyright © ${new Date().getFullYear()} Kinsta. Built with Docusaurus.`,
    },
  },
};
Footer Links

Ændring af links i sidefoden svarer til ændring af den øverste navbar: Find afsnittet footer i docusaurus.config.js og rediger det, indtil det passer til dine behov.

Her er, hvordan vi har ændret vores footer -sektion, så den ser ud:

footer: {
  style: 'dark',
  links: [
    {
      title: 'Docs',
      items: [
        {
          label: 'Kinsta starters',
          to: '/docs/intro',
        },
      ],
    },
    {
      title: 'Talk with us',
      items: [
        {
          label: 'Discord',
          href: 'https://discord.gg/vjRPMhFaBA',
        },
        {
          label: 'Support',
          href: 'https://kinsta.com/kinsta-support/',
        },
        {
          label: 'Twitter',
          href: 'https://twitter.com/kinsta',
        },
      ],
    },
    {
      title: 'More',
      items: [
        {
          label: 'Application Hosting',
          href: 'https://kinsta.com/application-hosting/',
        },
        {
          label: 'Database Hosting',
          href: 'https://kinsta.com/database-hosting/',
        },
        {
          label: 'WordPress Hosting',
          href: 'https://kinsta.com/wordpress-hosting/',
        },
        {
          label: 'DevKinsta',
          href: 'https://kinsta.com/devkinsta/',
        },
      ],
    },
  ],
};

Farver og CSS

Den klassiske forindstilling til Docusaurus bruger Infima CSS-framework. Med dette i tankerne har Docusaurus-skaberne lavet et meget nyttigt webværktøj til at hjælpe dig med at ændre farverne og andre CSS-elementer og -deklarationer.

Når du har indtastet dine præferencer på siden, vil værktøjet generere en custom.css-fil – komplet med en dejlig pakke af komplementerende toner – i løbet af få sekunder. Du kan derefter kopiere denne nye CSS-fil ind i dit projekts /src/css-mappe til reference.

Docusaurus' brugerdefinerede CSS-værktøj.
En del af Docusaurus’ officielle dokumentation, der viser deres brugerdefinerede CSS-værktøj med felter til at indtaste hex-kodejusteringer for hvert enkelt element i Docusaurus-designet.

Dokumentation

Al dokumentation på dit nye websted er gemt i mappen /docs. Du kan naturligvis ændre mappenavnet i docusaurus.config.js.

Du skal blot oprette markdown-filerne i din tekst- eller HTML-editor og lægge dem i den pågældende mappe. Hver fil skal se således ud:

---
id: the-id
title: Title
---
# Rest of the document

På baggrund af ID’et opretter Docusaurus URL’erne for artiklerne i den pågældende undermappe: yourdomain.com/docs/{id}

Vi kan også oprette undermapper, hvis vi ønsker at opdele vores dokumentation i forskellige, logiske afsnit. Vi skal dog gøre lidt ekstra arbejde for at få disse undermapper til at fungere som vi forventer.

Lad os sige, at vi opretter en ny dokumentmappe med navnet “Starters” Hvis vi derefter skulle opdatere hjemmesiden og klikke på det nye link “Starters”, der automatisk er tilføjet til vores sidebar, får vi en fejl – fordi der endnu ikke er nogen indeksside i vores nye mappe.

Den nemmeste måde at løse dette på er at oprette en _category_.json-fil, der genererer indekset for alle sider, der er gemt i denne mappe. Du behøver kun at tilføje følgende kode:

{
  "label": "Starters",
  "position": 2,
  "link": {
    "type": "generated-index",
    "description": "All Kinsta Starters"
  },
};

Som du kan se, regenereres sidebaren, så den passer til strukturen i dine filer. Det skyldes, at sidebar.js-filen indeholder denne tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],

Hvis du foretrækker at tage dig af dette selv, kan du bare ændre dette til noget i stil med dette:

tutorialSidebar: [
  'intro',
  'hello',
  {
    type: 'category',
    label: 'Tutorial',
    items: ['tutorial-basics/create-a-document'],
  },
],

Blog

Docusaurus indeholder et smart blogmodul. At have en blog på plads ved siden af dit hovedwebsted kan være meget nyttigt til at informere din brugerbase om ændringer der sker i dit projekt, eller til at holde løbende projektnoter som en form for ændringsbog.

Hvert indlæg består af en frontmatter-del, som denne:

---
slug: docusaurus-starter
title: Docusaurus Starter
authors: palmiak
tags: [starters, docusaurus]
---

…og selvfølgelig selve indholdet. Det har også et meget nyttigt tag, som hjælper med at begrænse det indlægsresumé, der vises på alle indlægslister.

Det er også en god idé at oprette en authors.yml-fil til credits. Filen ser således ud:

palmiak:
name: Maciek Palmowski
title: DevRel
url: https://github.com/palmiak
image_url: https://github.com/palmiak.png

Takket være denne fil har du alle forfatterdata på ét sted, så du nemt kan henvise til dem.

Sådan implementerer du dit Docusaurus-websted på Kinsta

Ud over WordPress-websteder, selvstændige applikationer og databaser kan Kinsta være host for statiske websteder.

Det betyder, at det er perfekt til dine Docusaurus-websteder – og til at administrere alle dine webprojekter – direkte fra dit MyKinsta-dashboard.

Når din applikation er blevet implementeret, vil du kunne gennemgå din applikations løbende analyser, både live og historiske, med målinger, herunder:

  • Båndbreddeforbrug
  • Byggetid
  • Køretid
  • CPU-forbrug
  • Hukommelsesforbrug

Fra start til slut tager implementeringsprocessen gennem MyKinsta kun få minutter.

Lad os komme i gang!

Forudsætninger: Konfigurering af dit Docusaurus-projekt

For at hoste dit Docusaurus-projekt på Kinsta’s Applikation Hosting-platform skal du:

  1. Medtage et navnefelt i din package.json-fil. (Dette kan være hvad som helst og vil ikke påvirke din implementering.)
  2. Medtage et build-script i din package.json-fil. (Dit Docusaurus-projekt bør allerede indeholde dette.)
  3. Installer serve npm-pakken og indstil startscriptet til serve build.

Når disse er afkrydset, kan du gå videre til den faktiske udrulning af dit websted.

Udrulning af dit Docusaurus-projekt

Følg disse enkle trin for at oprette forbindelse til din GitHub-konto og starte dit Docusaurus-websted:

  1. Log ind på din MyKinsta-konto, og gå til fanen Applikationer i menuen til venstre.
  2. Klik på den blå knap Tilføj tjeneste, og vælg Applikation fra rullelisten.

    Vælg "Applikation" under "Tilføj tjeneste" i MyKinsta.
    Fanen Applikationer i MyKinsta-dashboardet med musen svævende over indstillingen “Applikation” efter at have klikket på den blå “Tilføj tjeneste”-knap.

  3. Hvis du endnu ikke har oprettet forbindelse til din GitHub-konto via MyKinsta, vises der en modal, som opfordrer dig til at gøre det. Klik på knappen Fortsæt med GitHub for at fortsætte.

    Integrering af MyKinsta med GitHub.
    En modal med teksten “GitHub-integration: Forbind kinsta til dit GitHub-næverum her for at importere dine eksisterende repositorier.” Nederst til højre er der en hvid “Annuller”-knap og en blå “Fortsæt med GitHub”-knap.

  4. Der åbnes et nyt vindue, hvor du bliver bedt om tilladelse til at autorisere Kinsta til at få adgang til og administrere dine GitHub-ressourcer. Sørg for, at du er logget ind på den korrekte GitHub-konto, og klik derefter på den grønne knap Authorize Kinsta nederst i vinduet.

    Godkendelse af Kinsta hos GitHub.
    En godkendelsesmodal fra GitHub med teksten “Kinsta by Kinsta would like permission to: Verify your GitHub identity (kinstauser); Know which resources you can access; Act on your behalf” med både en grå “Cancel”-knap og en grøn “Authorize Kinsta”-knap i bunden.

  5. Du er nu kommet til guiden til GitHub-integration. Dette er det sidste trin, før du kan implementere dit websted. Overvej omhyggeligt de præsenterede felter, og udfyld dem i overensstemmelse med din GitHub-konfiguration og dit projekts krav. Hvis du har en Dockerfil i dit repository, kan du bruge denne til at opsætte containerimage; ellers opstiller Kinsta automatisk et containerimage for dig. Bemærk, at du muligvis skal redigere dine GitHub-tilladelser, før du kan fortsætte, især hvis dette er din første udstationering via Kinsta.
    Rediger GitHub-tilladelser.
    Den nye applikationsguide i MyKinsta viser musens hånd, der svæver over dropdown-indstillingen “Rediger GitHub-tilladelser” for feltet “GitHub repository”.

    Du kan vælge, om du vil give Kinsta adgang til alle repositorier eller kun til bestemte repositorier. Disse tilladelser kan til enhver tid justeres fra din GitHub-kontos indstillinger for applikationer.

    Valg af GitHub-tilladelser til at give Kinsta.
    GitHub-afsnittet “Permissions”, der viser to muligheder i afsnittet “Repository access”: “All repositories” eller “Only select repositories”.

  6. Når du har foretaget dine valg og bekræftet dine valg, vises dine implementeringsdetaljer samt mulighederne for at ændre indstillingerne eller genimplementere.
    Siden "Deployment details" i MyKinsta, der viser oplysninger vedrørende den implementerede app, herunder navnet på den implementerede filial, commit-nummeret, den ledsagende commit-meddelelse, implementeringstider og den valgte datacenterplacering.
    Siden “Deployment details” i MyKinsta, der viser oplysninger vedrørende den implementerede app, herunder navnet på den implementerede filial, commit-nummeret, den ledsagende commit-meddelelse, implementeringstider og den valgte datacenterplacering.

    Det er også her, du kan se eventuelle fejl, der opstod under implementeringen, sammen med oplysninger om, hvad der forårsagede fejlen, så du nemt kan afhjælpe den. Hvis du har svært ved at løse problemet, kan du finde yderligere vejledning om udrulningsfejl i Kinstas dokumentation.

    "Byggeproces mislykkedes" fejl med detaljer.
    En fejl med titlen “Build process failed” sammen med “Unknown build fail type” over en detaljerude med en liste over de individuelle fejl, der bidrog til fejlen.

Hvis du er kommet så langt uden fejl, så tillykke – du har netop udrullet dit Docusaurus-websted med succes via Kinsta! Din applikation (dvs. dit statiske websted) er tilgængelig, så snart du har afsluttet guiden. Du kan se den på din applikations URL, som normalt er https://your-docusaurus-site.kinsta.app.

Her er vores første kig på vores prøvesite på Kinsta:

Vores implementerede Docusaurus-websted.
Den indsatte Docusaurus-hjemmeside, hvor der øverst er et grønt banner med overskriften “My Site” og taglinen “Dinosaurs are cool” i hvid tekst.

Opsummering

Med sine overraskende kraftfulde funktioner, det venlige design, den intuitive navigation og fokus på indhold er det ikke svært at se, hvorfor Docusaurus betragtes som et fremragende værktøj for enhver udvikler, der ønsker nemt at implementere og vedligeholde et strømlinet, velorganiseret statisk dokumentationswebsted og/eller blog.

Skift dit webudviklingsspil! Sig farvel til klodset CMS og hej til Docusaurus - en simpel statisk webstedsgenerator, der ændrer udviklerspillet. 💥 Tjek det ud lige her ⬇️Klik for at Tweete

Når du har fyldt dit websted med indhold, som dine besøgende vil sætte pris på, vil du begynde at lægge mærke til yderligere indbyggede funktioner, som er praktiske. For eksempel er Docusaurus’ søgemaskineoptimeringsfunktioner perfekte til at hjælpe dig med at opnå forbedret synlighed gennem et bredere publikum, mens du arbejder på andre teknikker til at avancere i SEO-rangeringerne.

Har du bygget noget med Docusaurus? Del dine projekter og erfaringer med os i kommentarfeltet nedenfor.

Maciek Palmowski

Maciek is a web developer working at Kinsta as a Development Advocate Analyst. After hours, he spends most of his time coding, trying to find interesting news for his newsletters, or drinking coffee.