Voor lichtgewicht websites, applicaties en andere kleine projecten richten developers zich steeds vaker tot statische sitegeneratoren in plaats van WordPress of andere content management systemen (CMS’en). Statische sites bieden een eenvoudige en effectieve manier om websites en applicaties te maken die snel, veilig en gemakkelijk te onderhouden zijn.

Docusaurus is zo’n statische sitegenerator – en het wint snel aan populariteit in de devcommunity.

In dit artikel gaan we dieper in op de voordelen van het gebruik van Docusaurs als statische sitegenerator en waarom het een groeiende favoriet is onder developers.

Wat is Docusaurus?

Docusaurus is een populaire statische sitegenerator die React, een van de populairste JavaScript bibliotheken, gebruikt als UI bibliotheek voor het maken van pagina’s. Net als andere dergelijke generatoren is het eenvoudig in te stellen en aan te passen, en – het belangrijkste – het biedt je alles wat je nodig hebt om met je statische website aan de slag te gaan.

Wat Docusaurus echter onderscheidt, is dat het je helpt bij het maken en beheren van een website waarin content een belangrijke rol speelt. Hiermee kun je snel en gemakkelijk een volledige website bouwen – compleet met blogfeature- die je content vanaf het begin in de schijnwerpers zet.

Omdat bij Docusaurus de content centraal staat, is het perfect voor het maken van documentatiesites zoals wiki’s. Het maakt daarnaast gebruik van markdown, wat ideaal is voor samenwerking en opslag in een git repository. Bovendien heeft het een heleboel geweldige features zoals i18n, zoeken en customthema’s, die we later in meer detail zullen bespreken.

Dit zijn slechts enkele van de opvallende features die Docusaurus tot een solide optie maken:

  • Gebouwd met React
  • Ondersteuning voor MDX v1
  • Ondersteuning voor React component insluiten via Markdown
  • Versiebeheer van documenten
  • Compatibiliteit met Git, Crowdin en andere vertaalmanagers voor documentvertaling en bulk of individuele deployment

Wie gebruikt Docusaurus?

Docusaurus is gemaakt door Facebook, dus het is geen verrassing dat het momenteel wordt gebruikt door veel grote merken en bedrijven op het web.

Hier zijn slechts een paar van de grootste merken die Docusaurus vandaag gebruiken (en er zullen er binnenkort nog meer volgen naarmate de populariteit van Docusaurus blijft groeien):

En elke dag komen er meer bij.

Zo installeer je Docusaurus

Docusaurus is heel eenvoudig te installeren en kost maar een paar minuten. In deze handleiding bouwen we een documentatiesite met een blog, en passen we aan hoe de website eruit ziet.

En dit is het coolste deel: het kost ons minder dan een uur om alles op te starten.

Laten we beginnen!

Vereisten

Docusarus vereist Node.js 16.14 of nieuwer. Het is een flat-file SSG, wat betekent dat je geen extra database nodig hebt.

Als je nog geen Node.js 16.14+ beschikbaar hebt, moet je beginnen met het installeren van Node.js of je huidige versie upgraden. Daarna kun je overgaan tot het onderstaande installatieproces van Docusaurus.

We gaan de voorbeeldsite van Docusaurus uit deze GitHub repository gebruiken. Je kunt die gebruiken voor deze tutorial of een schone installatie van Docusaurus.

Installatieproces

Om het installatieproces van Docusaurus te beginnen, moet je eerst het volgende commando uitvoeren:

npx create-docusaurus@latest  classic

Dit zal een map aanmaken voor je project en daarin het klassieke thema scaffolden. Het klassieke thema bevat al enkele voorgeconfigureerde features zoals een blog, aangepaste pagina’s en een CSS framework.

Na de installatie moet je het volgende commando uitvoeren om de lokale server te starten:

npm start

Als je een geoptimaliseerde versie wilt bouwen die klaar is voor deployment, moet je in plaats daarvan dit uitvoeren:

npm run build

Structuur

Als je eenmaal je Docusaurus instantie hebt geïnstalleerd, kun je je projectmap openen en het “skelet” van je nieuwe site bekijken.

Zo ziet de bestandsstructuur eruit:

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

Er zijn een paar details op te merken over een paar van deze bestanden en mappen:

  • /blog: Bevat alle bestanden die met je blog te maken hebben.
  • /docs: Bevat alle bestanden met betrekking tot je documenten. Je kunt hun volgorde aanpassen in het sidebar.js bestand.
  • /src: Bevat alle niet-documentatie bestanden zoals pagina’s of aangepaste componenten.
  • /src/pages: Alle JSX/TSX/MDX bestanden worden omgezet in pagina’s.
  • /static: Statische bestanden die worden gekopieerd naar de uiteindelijke bouwmap.
  • docusaurus.config.js: Docusaurus configuratiebestand.
  • packaged.json: Elke Docusaurus site is een React app, dus hier vind je alle dependencies en scripts die het gebruikt voor React.
  • sidebar.js: Hier kun je de volgorde van de documenten in de zijbalk opgeven.

Je Docusaurus installatie aanpassen

Zoals je kunt zien aan de eenvoud van zijn bestandsstructuur, is Docusaurus gemakkelijk te gebruiken en te navigeren. Ook het aanpassen van je Docusaurus site is een fluitje van een cent. Je kunt deze bestanden openen en bewerken met jefavoriete tekstverwerker of IDE.

Laten we enkele van de aanpassingsmogelijkheden die je meteen kan uitvoeren.

Homepagina

Het eerste wat je waarschijnlijk wilt doen is de standaard homepagina aanpassen om je eigen project weer te geven. Gelukkig is het niet moeilijk om de homepagina van Docusaurus aan te passen.

Om de homepagina te veranderen, open je het bestand src/pages/index.js en maak je daar aanpassingen. Het is een typische React pagina, dus je kunt hem wijzigen of herbouwen door de inhoud te veranderen of aangepaste React componenten te maken.

Configuratiebestand

Vervolgens duiken we in het cruciale docusaurus.config.js bestand en veranderen we enkele belangrijke details voor onze instantie.

Naam en beschrijving

In het configuratiebestand vind je:

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

Verander deze details naar de behoeften van je site en sla het bestand dan op.

Navigatiebalk

Om je navigatiebalk te bewerken, zoek je het item navbar.

In ons voorbeeld willen we een link naar Kinsta toevoegen, het item “Tutorial” hernoemen naar “Starter documentation”, en het Kinsta logo toevoegen.

Dit is hoe we het zouden doen:

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

Het aanpassen van de footer in Docusaurus bestaat uit twee delen: de footer zelf en de footerlinks.

Footer content

Het grootste deel van de content van de footer (exclusief de lijst met links) kan worden geplaatst in het bestand themeConfig.footer. Dit is de ideale plaats om een logo en een copyrightmelding toe te voegen.

Hier zie je hoe we onze footerconfiguratie hebben aangepast:

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

Het wijzigen van de footerlinks is vergelijkbaar met het wijzigen van de bovenste navigatiebalk: Zoek de sectie footer in docusaurus.config.js en bewerk tot het aan je wensen voldoet.

Hier zie je hoe we onze sectie footer hebben veranderd:

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

Kleuren en CSS

De klassieke preset voor Docusaurus gebruikt het Infima CSS framework. Met dit in gedachten hebben de makers van Docusaurus een zeer handige webtool gemaakt om je te helpen de kleuren en andere CSS elementen en declaraties te veranderen.

Zodra je je voorkeuren op de pagina hebt ingevoerd, genereert de tool in enkele seconden een custom.css bestand – compleet met een mooie reeks complementaire tinten. Je kunt dit nieuwe CSS bestand vervolgens kopiëren naar de /src/css map van je project ter referentie.

Docusaurus' custom CSS tool.
Een deel van de officiële documentatie van Docusaurus, met daarin hun custom CSS tool met velden om hexcode aanpassingen in te voeren voor elk individueel element in het Docusaurus ontwerp.

Documentatie

Alle documentatie over je nieuwe website wordt opgeslagen in de map /docs. Natuurlijk kun je de mapnaam veranderen in docusaurus.config.js.

Maak de markdownbestanden aan in je tekst of HTML editor en zet ze in die map. Elk bestand moet er zo uitzien:

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

Op basis van het ID bouwt Docusaurus de URL’s voor de artikelen in die submap: yourdomain.com/docs/{id}

We kunnen ook submappen maken als we onze documentatie in verschillende, logische secties willen verdelen. We moeten echter wat extra werk doen om deze submappen te laten functioneren zoals we verwachten.

Stel dat we een nieuwe documentenmap Starters maken. Als we dan de homepage verversen en op de nieuwe link “Starters” klikken die automatisch aan onze zijbalk is toegevoegd, krijgen we een foutmelding – omdat er nog geen indexpagina in onze nieuwe map staat.

De eenvoudigste manier om dit op te lossen is door een _category_.json bestand te maken dat de index genereert van alle pagina’s die in deze map zijn opgeslagen. Je hoeft alleen de volgende code toe te voegen:

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

Zoals je ziet, regenereert de zijbalk om overeen te komen met de structuur van je bestanden. Dat komt omdat het sidebar.js bestand deze tutorialSidebar bevat: [{type: 'autogenerated', dirName: '.'}],

Als je dit liever zelf regelt, kun je dit gewoon veranderen in iets als dit:

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

Blog

Docusaurus bevat een handige blogmodule. Een blog naast je hoofdwebsite kan heel nuttig zijn om je gebruikers op de hoogte te houden van veranderingen in je project, of om projectnotities bij te houden als een soort logboek.

Elk bericht bestaat uit een frontmatter deel, zoals dit:

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

…en natuurlijk de content zelf. Het heeft ook een heel handige <!--truncate--> tag, die helpt om de samenvatting van het bericht te beperken die bij alle berichten wordt getoond.

Het is ook een goed idee om een authors.yml bestand te maken voor credits. Het bestand ziet er als volgt uit:

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

Dankzij dit bestand heb je alle gegevens van de auteur op één plaats voor gemakkelijke referentie.

Zo deploy je je Docusaurus website bij Kinsta

Naast WordPress sites, stand-alone applicaties en databases kan Kinsta ook statische sites hosten.

Het is dus perfect voor je Docusaurus sites – en voor het beheren van al je webprojecten – rechtstreeks vanaf je MyKinsta dashboard.

Zorg ervoor dat je eerst je code naar een Git provider van voorkeur (Bitbucket, GitHub of GitLab) pusht en volg dan deze stappen om je statische site te deployen naar Kinsta:

  1. Login of maak een account aan om je MyKinsta’s dashboard te bekijken.
  2. Autoriseer Kinsta met je Git provider.
  3. Klik op Statische sites in de linker zijbalk, klik dan op Site toevoegen.
  4. Selecteer de repository en de branch waarvan je wilt deployen.
  5. Geef je site een unieke naam.
  6. Voeg de build instellingen toe in het volgende formaat:
    • Build commando: npm run build
    • Node versie: 18.16.0
    • Publish directory: build
  7. Klik ten slotte op Site maken.

Als je zover bent gekomen zonder fouten, dan gefeliciteerd – je hebt je Docusaurus site succesvol gedeployd bij Kinsta!

Hier is onze eerste blik op onze voorbeeldsite op Kinsta:

Onze deployed Docusaurus-site.
De gedeployde Docusaurus homepagina, met bovenaan een groene banner met de kop “My Site” en de tagline “Dinosaurs are cool” in witte tekst.

Als alternatief voor Statische Site Hosting kun je ervoor kiezen om je statische site te deployen met Kinsta’s Applicatie Hosting, die meer flexibiliteit biedt bij het hosten, een breder scala aan voordelen en toegang tot robuustere features. Bijvoorbeeld schaalbaarheid, custom deployments met behulp van een Dockerfile en uitgebreide analytics met real-time en historische gegevens.

Samenvatting

Met zijn verrassend krachtige mogelijkheden, vriendelijke ontwerp, intuïtieve navigatie en focus op content, is het niet moeilijk te zien waarom Docusaurus wordt beschouwd als een uitstekend tool voor elke developer die gemakkelijk een gestroomlijnde, goed georganiseerde statische documentatiesite en/of blog wil implementeren en onderhouden.

Als je je site eenmaal hebt gevuld met content die je bezoekers zullen waarderen, zul je merken dat de extra ingebouwde features van pas komen. De zoekmachineoptimalisatiemogelijkheden van Docusaurus zijn bijvoorbeeld perfect om je te helpen een betere zichtbaarheid te krijgen bij een breder publiek, terwijl je werkt aan andere technieken om vooruit te komen in de SEO rankings.

Heb jij iets gebouwd met Docusaurus? Deel je projecten en ervaringen met ons in het commentsveld hieronder.

Maciek Palmowski

Maciek is een web developer en werkt bij Kinsta als Development Advocate Analyst. Na werktijd besteedt hij de meeste tijd aan coderen, interessant nieuws zoeken voor zijn nieuwsbrieven of koffie drinken.