Hoppa till huvudinnehåll

Att migrera dokumentation till Docusaurus

· 3 min att läsa
Ola Davidsson
Ola Davidsson
Docs Developer and Technical Writer

Har du dokumentation som ligger utspridd i olika format, verktyg och system? Att samla allt på ett ställe kan kännas överväldigande, men med en tydlig plan kan det bli enklare än du tror. Här är en steg-för-steg-guide för att migrera din dokumentation till Docusaurus.

Varför Docusaurus?​

Innan vi dyker in i hur, låt oss prata om varför. Här är några av fördelarna med Docusaurus:

  • Modern design – Användarvänliga och professionella sajter utan krånglig kod.
  • Flexibilitet – Stöd för både statiskt och interaktivt innehåll.
  • Enkel hosting – Sajten fungerar utmärkt på Netlify, Vercel eller GitHub Pages.
  • Open source – Ingen licenskostnad.

Steg 1: Planera din migrering​

Kartlägg ditt innehåll​

Samla information om:

  • Var dokumentationen finns idag (Google Docs, Confluence, wikis, etc.).
  • Hur materialet är organiserat.
  • Vilka dokument som är relevanta och vilka som kan arkiveras.

Definiera strukturen​

Skapa en tydlig plan för hur innehållet ska organiseras i Docusaurus:

  • Kategorier – Exempelvis "Kom igång", "API-dokumentation", och "Vanliga frågor".
  • Hierarki – Docusaurus använder mappar för att skapa en naturlig struktur.

Steg 2: Importera innehållet​

Konvertera till Markdown​

Docusaurus baseras på Markdown, så det är viktigt att konvertera ditt innehåll till detta format.
Här är några verktyg som kan hjälpa:

  • Docs to Markdown – Konverterar Google Docs till Markdown.
  • Pandoc – Ett kraftfullt verktyg för att konvertera mellan olika dokumentformat.

Placera filer i rätt mappar​

Lägg dina Markdown-filer i docs-mappen i ditt Docusaurus-projekt. Exempel:

docs/ 
├── Kom-igång/ 
│ ├── intro.md 
│ ├── installation.md 
├── API/ 
│ ├── auth.md 
│ ├── endpoints.md

Steg 3: Lägg till metadata​

För att göra dokumentationen lättnavigerad, lägg till metadata i början av varje Markdown-fil. Exempel:

---
title: "Introduktion"
sidebar_position: 1
description: "Lär dig grunderna om vår plattform."
---

Steg 4: Anpassa designen​

Anpassa sidebar​

Uppdatera din sidebars.js-fil för att spegla den nya strukturen. Exempel:

module.exports = {
  tutorialSidebar: [
    {
      type: 'category',
      label: 'Kom igång',
      items: ['Kom-igång/intro', 'Kom-igång/installation'],
    },
    {
      type: 'category',
      label: 'API',
      items: ['API/auth', 'API/endpoints'],
    },
  ],
};

Lägg till en sökfunktion​

Integrera Algolia för att förbättra användarupplevelsen. Det gör det enkelt att hitta rätt information snabbt.

Steg 5: Publicera din sajt​

När allt innehåll är på plats och strukturen känns bra är det dags att publicera sajten. Använd en hostingtjänst som:

  • Netlify – Smidig integration och gratis för små projekt.
  • Vercel – Optimerad för statiska sajter.
  • GitHub Pages – Perfekt för enklare projekt.