Heb jij een waardevol artikel voor onze kennisbank? Wij plaatsen hem graag.

Aanleveren​

Er zijn verschillende manieren om een kennisbankartikel aan te dragen:

Optie 1: Stuur ons een e-mail​

Stuur een e-mail naar developer.overheid@geonovum.nl met het markdown-bestand van jouw artikel.

Optie 2: Maak een Gist en dien een issue in​

Je kunt een artikel schrijven in Markdown en deze als een Gist opslaan. Zorg ervoor dat je de Gist openbaar maakt en de link naar de Gist deelt in een issue.

Optie 3: Maak een Pull Request (onze favoriet)​

Je kunt een artikel direct als pull request aanbieden. Plaats het bestand in de juiste map onder docs/ (zie Mappenstructuur hieronder).

Als je nog geen lid bent van onze repository, maak dan eerst een fork. Deze fork kun je vervolgens aanbieden als pull request bij ons.

Markdown​

• Artikelen worden aangeleverd als Markdown-bestand (.md of .mdx extensie).
• De bestandsnaam is de slug van het artikel, bijvoorbeeld: mijn-artikel-over-oauth.md.

Frontmatter​

Elk artikel begint met frontmatter in YAML-formaat. Hierin staan metadata die door de site worden gebruikt:

---
title: "Aan de slag met OAuth 2.0"
description:
  "OAuth 2.0 is een open standaard voor autorisatie die veel wordt gebruikt bij
  de Nederlandse overheid."
image: ./img/oauth-overview.png
content_type: standaard
tags:
  - informatiebeveiliging
  - oauth
---

Description (verplicht)​

Het description veld is verplicht. Dit wordt gebruikt in de RSS-feed en als meta-beschrijving voor zoekmachines. Gebruik bij voorkeur de eerste zin van je artikel.

Image (optioneel, aanbevolen)​

Het image veld is optioneel maar aanbevolen. Deze afbeelding wordt gebruikt als preview wanneer het artikel wordt gedeeld op sociale media (Open Graph). Plaats de afbeelding in dezelfde map als het artikel of in een img/-submap.

Content type​

Het content_type veld bepaalt in welke overzichten het artikel verschijnt en welke sectieopbouw wordt verwacht. Kies het type dat het beste past:

Het content_type veld staat los van de tags. Content types mogen niet als tag voorkomen.

Tags​

We hanteren een taggingstrategie met 4 lagen:

Laag 1: Content type (geen tag)​

Content type is een apart frontmatter veld (zie hierboven), niet een tag. De waarden standaard, tool, tutorial, architectuur en richtlijn mogen nooit als tag voorkomen.

Laag 2: Thema-tags (verplicht, 1-3 per artikel)​

Elk artikel moet minimaal 1 en maximaal 3 thema-tags hebben:

Laag 3: Onderwerp-tags (optioneel, 0-5 per artikel)​

Specifieke technologieën, standaarden of concepten. Voorbeelden: oauth, oidc, kubernetes, docker, react, dcat, wcag, haven.

Laag 4: Organisatie-tags (optioneel)​

Bijvoorbeeld: forum-standaardisatie, kennisplatform-apis, vng, common-ground.

Regels​

• Maximaal 8 tags totaal per artikel.
• Alle tags moeten voorkomen in tags.yml. Een onbekende tag laat de build falen.

Mappenstructuur​

Artikelen staan in docs/ in een van de 7 themacategorieën, elk met subcategorieën per content type:

docs/
├── api-ontwikkeling/
│   ├── standaarden/
│   ├── architectuur/
│   ├── tutorials/
│   └── tools/
├── front-end/
│   ├── standaarden/
│   └── tools/
├── data/
│   ├── standaarden/
│   └── linked-data/
├── security/
│   ├── authenticatie/
│   ├── wetgeving-en-beleid/
│   ├── standaarden/
│   └── tools/
├── devops/
│   ├── standaarden/
│   └── tools/
├── open-source/
│   ├── standaarden/
│   ├── tutorials/
│   └── tools/
└── leidraad/

Plaats je artikel in de map die past bij het thema en het content type. Bijvoorbeeld een tool-artikel over security gaat in docs/security/tools/.

Sectieopbouw per content type​

Elk content type heeft een verwachte sectieopbouw (H2-koppen). Je hoeft niet elk kopje te vullen, maar probeer de structuur aan te houden:

Standaard​

## Waarom deze standaard

## Wanneer gebruik je dit

## Hoe werkt het

## Toepassing in Nederland

## Bronnen

Tool​

## Kenmerken

## Hoe werkt het

## Aan de slag

## Waarom deze tool

## Alternatieven

## Bronnen

Tutorial (single-page)​

## Wat je gaat maken

## Vereisten

## Stappen

## Resultaat

## Bronnen

Tutorial (multi-page)​

Een multi-page tutorial bestaat uit een index.md met een overzicht en genummerde stap-bestanden (1-eerste-stap.md, 2-tweede-stap.md, etc.).

index.md:

## Wat je gaat maken

## Vereisten

## Stappen

## Bronnen

Architectuur​

## Het probleem

## De oplossing

## Kernconcepten

## Wanneer gebruik je dit

## Best practices

## Gerelateerde patronen

## Bronnen

Voorbeeld​

Hieronder een compleet voorbeeld van een kennisbankartikel:

---
title: "Security.txt"
content_type: standaard
tags:
  - informatiebeveiliging
---

# Security.txt

Een korte introductie over wat security.txt is.

## Waarom deze standaard

Uitleg over de voordelen en het belang van security.txt.

## Wanneer gebruik je dit

In welke situaties zet je security.txt in.

## Hoe werkt het

Technische uitleg van het formaat en de werking.

## Toepassing in Nederland

Hoe wordt security.txt toegepast bij de Nederlandse overheid.

## Bronnen

- [securitytxt.org](https://securitytxt.org/)