Skapa och anpassa en Docusaurus-webbplats (med bloggfunktion)

För exempelvis lättviktiga webbplatser, applikationer och andra små projekt så använder allt fler utvecklare statiska webbplatsgeneratorer framför WordPress eller andra innehållshanteringssystem (CMS). Statiska webbplatser är ett enkelt och effektivt sätt att skapa webbplatser och applikationer som är snabba, säkra och lätta att underhålla.

Docusaurus är en sådan statisk webbplatsgenerator – och den ökar snabbt i popularitet i varje utvecklings-community.

I det här inlägget så gör vi en djupdykning i fördelarna med att använda Docusaurus som statisk webbplatsgenerator. Vi går dessutom igenom varför det är en växande favorit bland utvecklare.

Vad är Docusaurus?

Docusaurus är en populär statisk webbplatsgenerator som använder React som sitt UI-bibliotek för skapande av sidor. Det är ett av de främsta JavaScript-biblioteken. Precis som andra sådana generatorer så är den lätt att installera och lätt att ändra. Den ger dig dessutom allt som du behöver för att komma igång med din statiska webbplats.

Det som skiljer Docusaurus från andra är dock att den hjälper dig att skapa och hantera en webbplats där innehållet spelar en nyckelroll. Som ett resultat så kan du snabbt och enkelt bygga en fullständig webbplats – komplett med en bloggfunktion – som lyfter fram ditt innehåll redan från början.

Eftersom innehållet är i fokus med Docusaurus så är det exempelvis perfekt för att skapa dokumentations-sidor som wikis. Den använder dessutom markdown, vilket är idealiskt både för samarbete och lagring i ett git-arkiv. Utöver detta så har den massor av fantastiska funktioner som i18n, sökning och anpassade teman, som vi kommer att diskutera mer ingående senare.

Här är bara några av de utmärkande funktionerna som gör Docusaurus till ett bra alternativ:

• Byggd med hjälp av React
• Stöd för MDX v1
• Stöd för inbäddning av React-komponenter via Markdown
• Versionering av dokument
• Kompatibilitet med Git, Crowdin och andra översättningshanterare för översättning av dokument och massdistribuering eller individuell distribuering

Vem använder Docusaurus?

Docusaurus skapades av Facebook. Det är därför ingen överraskning att den för närvarande används av många stora varumärken och företag på hela webben.

Här är bara några av de största varumärkena som använder Docusaurus idag (och fler kommer att tillkomma när Docusaurus popularitet fortsätter att öka):

• Algolia DocSearch
• Jest
• React Native
• Supabase

Och fler ansluter sig till dem varje dag.

Hur man installerar Docusaurus

Docusaurus är mycket enkelt att installera och tar bara några minuter. I den här handledningen så kommer vi att bygga en dokumentations-webbplats med en blogg. Vi kommer därefter att anpassa hur webbplatsen ser ut.

Och här kommer den coolaste delen: Det kommer att ta oss mindre än en timme att starta upp allt.

Låt oss köra igång!

Krav

Docusarus kräver Node.js 16.14 eller senare. Det är en SSG med platta filer. Som ett resultat så behöver du inte någon extra databas.

Om du inte redan har Node.js 16.14+ tillgängligt så måste du börja med att installera Node.js eller uppgradera din nuvarande version. Därefter så kan du gå vidare till Docusaurus installationsprocess nedan.

Vi kommer dessutom att använda Docusaurus exempelwebbplats från det här GitHub-arkivet. Du kan använda den eller en ren installation av Docusaurus för den här handledningen.

Installationsprocess

För att påbörja installationen av Docusaurus så måste du först köra följande kommando:

npx create-docusaurus@latest  classic

Detta kommer sedan att skapa en mapp för ditt projekt och ställa in det klassiska temat i den. Det klassiska temat inkluderar redan några förkonfigurerade funktioner som en blogg, anpassade sidor och ett CSS-ramverk.

Efter installationen så måste du sedan köra följande kommando för att starta den lokala servern:

npm start

Om du vill bygga en optimerad version som är redo att distribueras så bör du köra detta istället:

npm run build

Struktur

När du har installerat din Docusaurus-instans så kan du därefter öppna din projekt-katalog och titta närmare på ”skelettet” för din nya webbplats.

Så här ser filstrukturen ut:

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

Det finns några detaljer att notera när det gäller några av dessa filer och mappar:

• /blog: Den innehåller alla filer som är relaterade till din blogg.
• /docs: I denna mapp så finns alla filer som rör dina dokument. Du kan anpassa deras ordning i filen sidebar.js.
• /src: Innehåller alla filer som inte är dokumentationsfiler, exempelvis sidor eller anpassade komponenter.
• /src/pages: Alla JSX/TSX/MDX-filer som kommer att omvandlas till sidor.
• /static: Statiska filer som kommer att kopieras till den slutliga byggmappen.
• docusaurus.config.js: Konfigurationsfil för Docusaurus.
• packaged.json: Varje Docusaurus-webbplats är en React-app, så här hittar du alla beroenden och skript som den använder för React.
• sidebar.js: Här kan du ange ordningen på dokumenten i sidofältet.

Anpassa din Docusaurus-installation

Som du kan se av den enkla filstrukturen så är Docusaurus lätt att använda och navigera i. Det är dessutom enkelt att anpassa din Docusaurus-webbplats. Du kan exempelvis öppna och redigera dessa filer med din favorit-textredigerare eller IDE.

Låt oss gå igenom några av de anpassningsalternativ som du får direkt ur lådan.

Hemsida

Det första som du förmodligen kommer att vilja göra är att anpassa standard-hemsidan så att den visar ditt eget projekt. Processen för detta är som tur är väldigt okomplicerad, du kan enkelt göra de ändringar som du vill på Docusaurus hemsida.

För att ändra hemsidan så öppnar du filen src/pages/index.js och gör justeringarna direkt där. Det är en typisk React-sida. Som ett resultat så kan du ändra eller bygga om den genom att ändra innehållet eller skapa egna React-komponenter.

Konfigurationsfil

Därefter så ska vi dyka ner i den viktiga filen docusaurus.config.js och ändra några viktiga detaljer för vår instans.

Namn och beskrivning

I konfigurationsfilen så hittar du följande:

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

Ändra bara dessa detaljer för att passa din webbplats behov och spara sedan filen.

Navigeringsfältet

Om du vill redigera navigationsfältet så hittar du navbar.

I vårt exempel här så vill vi lägga till en länk till Kinsta, byta namn på objektet ”Tutorial” till ”Starter documentation” och lägga till Kinsta-logotypen.

Så här skulle vi göra:

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',
    },
  ],
},

Sidfot

Anpassning av sidfoten i Docusaurus består av två delar: själva innehållet i sidfoten och länkarna i sidfoten.

Innehållet i sidfoten

Huvuddelen av ditt innehåll i sidfoten (exklusive länklistan) kan placeras i din themeConfig.footer-fil. Detta är den idealiska platsen för att lägga till en logotyp och ett upphovsrättsmeddelande.

Så här har vi ändrat vår konfiguration för sidfoten:

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.`,
    },
  },
};

Länkar i sidfoten

Att ändra länkarna i sidfoten är ungefär som att ändra navigeringsfältet i toppen: Hitta avsnittet footer i docusaurus.config.js och redigera sedan detta tills det passar dina behov.

Så här har vi ändrat avsnittet footer:

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/',
        },
      ],
    },
  ],
};

Färger och CSS

Den klassiska förinställningen för Docusaurus använder Infima CSS-ramverket. Med detta i åtanke så har skaparna av Docusaurus gjort ett mycket användbart webbverktyg som hjälper dig att ändra färger och andra CSS-element och deklarationer.

När du har angett dina preferenser på sidan så genererar verktyget en custom.css-fil – komplett med en härlig svit av kompletterande toner – på några sekunder. Du kan sedan kopiera denna nya CSS-fil till projektets /src/css-katalog som referens.

Dokumentation

All dokumentation om din nya webbplats lagras i mappen /docs. Du kan naturligtvis ändra mappnamnet i docusaurus.config.js.

Det är bara att skapa markdown-filerna i din text- eller HTML-redigerare och släppa dem i den mappen. Varje fil ska se ut så här:

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

Docusaurus skapar webbadresserna för artiklarna i den undermappen utifrån ID: t: yourdomain.com/docs/{id}

Vi kan dessutom skapa undermappar om vi vill dela upp vår dokumentation i olika logiska avsnitt. Det krävs dock lite extra arbete för att dessa undermappar ska fungera på det sätt som vi förväntar oss.

Säg att vi skapar en ny dokumentmapp som heter ”Starters” Om vi sedan uppdaterar hemsidan och klickar på den nya länken ”Starters” som automatiskt läggs till i vår sidofält, får vi ett fel. Det finns ju inte någon indexsida i vår nya mapp ännu.

Det enklaste sättet för att åtgärda detta är att skapa en _category_.json-fil som genererar index för alla sidor som lagras i den här mappen. Du behöver bara lägga till följande kod:

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

Som du kan se så förnyas sidofältet för att matcha strukturen i dina filer. Detta beror på att filen sidebar.js innehåller den här tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],

Om du föredrar att ta hand om detta på egen hand så kan du bara ändra detta till något liknande:

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

Blog

Docusaurus inkluderar en smart bloggmodul. Att ha en blogg vid sidan av din huvudwebbplats kan exempelvis vara mycket användbart för att informera din användarbas om förändringar som sker i ditt projekt. Du kan dessutom föra löpande projektanteckningar som en form av ändringslogg.

Varje inlägg består av en del av en frontmatterdel, som här:

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

…och naturligtvis själva innehållet. Det finns även en mycket användbar <!--truncate-->-tagg, som hjälper till att begränsa den sammanfattning av inlägget som visas på alla inläggslistor.

Det är dessutom en bra idé att skapa en authors.yml-fil för krediter. Filen ser ut så här:

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

Tack vare den här filen så har du alla författaruppgifter på ett ställe för en enkel hänvisning.

Så här distribuerar du din Docusaurus-webbplats på Kinsta

Utöver WordPress-webbplatser, fristående applikationer och databaser så kan Kinsta hosta statiska webbplatser.

Som ett resultat så blir detta perfekt för dina Docusaurs-webbplatser – och för att hantera alla dina webbprojekt – direkt från din MyKinsta-instrumentpanel.

När din applikation har distribuerats så kan du granska applikationens löpande analyser, både live och historiskt, med mätningar som exempelvis:

• Användning av bandbredd
• Byggtid
• Körtid
• CPU-användning
• Användning av minne

Från början till slut så tar distribuerings-processen via MyKinsta endast några minuter.

Låt oss komma igång!

Förutsättningar: Konfigurera ditt Docusaurus-projekt

Om du vill hosta ditt Docusaurus-projekt på Kinsta’s plattform för applikationshosting så måste du göra följande:

1. Inkludera ett namnfält i din package.json-fil. (Detta kan vara vad som helst och kommer inte att påverka din distribuering.)
2. Inkludera ett byggskript i din package.json-fil. (Ditt Docusaurus-projekt bör redan innehålla detta.)
3. Installera serve npm-paketet och ställ in startskriptet till serve build.

När detta är gjort så kan du gå vidare till att faktiskt distribuera din webbplats.

Distribuera ditt Docusaurus-projekt

Följ dessa enkla steg för att ansluta till ditt GitHub-konto och starta din Docusaurus-webbplats:

1. Logga in på ditt MyKinsta-konto och navigera till fliken Applikationer i vänstermenyn.
2. Klicka på den blå knappen Lägg till tjänst och välj Applikationer från rullgardinsmenyn.

   

3. Om du ännu inte har anslutit till ditt GitHub-konto via MyKinsta så visas en modal som uppmanar dig att göra detta. Klicka sedan på knappen Fortsätt med GitHub för att fortsätta.

   

4. Ett nytt fönster öppnas och ber om ditt tillstånd att auktorisera Kinsta att få tillgång till och hantera dina GitHub-resurser. Kontrollera att du är inloggad på rätt GitHub-konto och klicka sedan på den gröna knappen Auktorisera Kinsta längst ner.

   

5. Du har nu kommit till guiden för GitHub-integrering. Detta är det sista steget innan du kan distribuera din webbplats. Tänk noga på fälten som presenteras och fyll sedan i dem enligt din GitHub-konfiguration och ditt projekts krav. Om du har en Dockerfil i ditt arkiv så kan du använda den för att ställa in container-avbildningen. Annars så ställer Kinsta in en containeravbildning åt dig automatiskt. Observera att du kan behöva redigera dina GitHub-behörigheter innan du kan fortsätta, särskilt om detta är din första distribuering via Kinsta.

   

   Du kan välja om du vill ge Kinsta åtkomst till alla arkiv eller endast specifika arkiv. Dessa behörigheter kan justeras när som helst från inställningarna för applikationer på ditt GitHub-konto.

   

6. När du har gjort dina val och bekräftat dem så visas sedan detaljerna för distribueringen och alternativ för att ändra inställningar eller distribuera om.

   

   Det är dessutom här som du ser eventuella fel som uppstod under distribueringen, tillsammans med information om vad som orsakade felet så att du enkelt kan åtgärda det. Om du har svårt att åtgärda problemet så kan du hitta ytterligare vägledning om distribuerings-fel i Kinsta’s dokumentation.

   

Om du har kommit så här långt utan fel, grattis – du har just lyckats distribuera din Docusaurus-webbplats via Kinsta! Din applikation (dvs. din statiska webbplats) är tillgänglig så snart som du har slutfört guiden. Du kan se den på din applikations webbadress, som vanligtvis är https://your-docusaurus-site.kinsta.app.

Här är en första titt på vår exempelwebbplats på Kinsta:

Sammanfattning

Med sina överraskande kraftfulla funktioner, sin vänliga design, intuitiva navigering och fokus på innehållet så är det inte svårt att se varför Docusaurus anses vara ett utmärkt verktyg för alla utvecklare. Det gör det enkelt att distribuera och underhålla en strömlinjeformad, välorganiserad statisk dokumentationswebbplats och/eller blogg.

Har du fyllt din webbplats med innehåll som dina besökare kommer att uppskatta? Då kommer du sedan att börja notera ytterligare inbyggda funktioner som kommer till nytta. Docusaurus möjligheter till sökmotoroptimering är exempelvis perfekta för att hjälpa dig att få en förbättrad synlighet genom en bredare målgrupp medan du arbetar med andra tekniker för att avancera i SEO-placeringarna.

Har du byggt något med Docusaurus? Dela dina projekt och erfarenheter med oss i kommentarsfältet nedan.

Maciek Palmowski

Maciek är en webbutvecklare som arbetar på Kinsta som Development Advocate Analyst. Efter jobbet ägnar han det mesta av sin tid åt att koda, försöka hitta intressanta nyheter till sina nyhetsbrev eller dricka kaffe.