Opret og tilpas et Docusaurus-websted (med blogfunktion)

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.

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

• Algolia DocSearch
• Jest
• React Native
• Supabase

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.

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 hoste statiske websteder.

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

Sørg for først at skubbe din kode til en foretrukken Git-udbyder (Bitbucket, GitHub, eller GitLab), og følg derefter disse trin for at implementere dit statiske websted til Kinsta:

1. Log ind eller opret en konto for at se dit MyKinsta dashboard.
2. Godkend Kinsta med din Git-udbyder.
3. Klik på Statiske websteder i venstre sidebar, og klik derefter på Tilføj websted.
4. Vælg lageret og den filial, du ønsker at implementere fra.
5. Tildel et unikt navn til dit websted.
6. Tilføj byggeindstillingerne i følgende format:
   • Build kommando: npm run build
   • Nodeversion: 18.16.0
   • Udgiv bibliotek: build
7. Klik til sidst på Opret websted.

Hvis du er kommet så langt uden fejl, så tillykke – du har med succes implementeret dit Docusaurus-websted gennem Kinsta!

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

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.

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 er en webudvikler, der arbejder hos Kinsta som Development Advocate Analyst. Efter timer bruger han det meste af sin tid på at kode, forsøge at finde interessante nyheder til sine nyhedsbreve eller drikke kaffe.