Hoe bouw je een aangepast WordPress-blokthema met theme.json: een stapsgewijze handleiding

Samenvatting

Het bouwen van een aangepast WordPress-blokthema met Full Site Editing (FSE) kan overweldigend lijken, maar theme.json vereenvoudigt het proces. Deze gids leidt je door het opzetten van een minimaal blokthema, het definiëren van globale stijlen zoals kleuren en typografie in theme.json, en het maken van aangepaste sjablonen met blokmarkup. Je leert blokpatronen en stijlvariaties toevoegen, waarmee je een volledig ontwerpbare site creëert zonder PHP-sjabloonbestanden. We behandelen veelgemaakte fouten, zoals het mengen van klassieke en blokthemafuncties, en laten zien hoe je je thema test. Aan het einde heb je een modern, uitbreidbaar blokthema klaar voor productie. Deze aanpak maakt gebruik van de nieuwste mogelijkheden van WordPress voor snellere, meer visuele ontwikkeling.

Inleiding

Full Site Editing (FSE) heeft de ontwikkeling van WordPress-thema's gerevolutioneerd, waardoor je elk deel van je site visueel kunt ontwerpen. Maar veel ontwikkelaars vertrouwen nog steeds op klassieke thema's of worstelen om blokthema's helemaal zelf te maken. De sleutel tot het ontsluiten van de kracht van FSE is theme.json—een configuratiebestand dat globale stijlen, instellingen en sjablonen beheert. Dit artikel biedt een praktische, stapsgewijze handleiding voor het bouwen van een aangepast blokthema met theme.json. Je leert de mapstructuur opzetten, kleurenpaletten en typografiepresets definiëren, aangepaste sjablonen maken met blokmarkup en stijlvariaties toevoegen. Aan het einde heb je een productieklaar blokthema dat eenvoudig te onderhouden en uit te breiden is. Laten we duiken en FSE-ontwikkeling ontraadselen.

Voor een bredere blik op hoe FSE de toekomst van WordPress-ontwerp vormgeeft, bekijk Gutenberg FSE: de toekomst van WordPress-ontwerp in 2026.

1. Een minimaal blokthema opzetten

Een blokthema vereist minimaal twee bestanden: style.css en index.html. Laten we ze maken.

Mapstructuur

Maak een map met de naam my-block-theme in je wp-content/themes/-directory. Plaats daarin:

• style.css
• index.html
• (optioneel) theme.json

style.css

Hoewel blokthema's minder afhankelijk zijn van CSS, is style.css nog steeds vereist voor thema-identificatie:

/*
Theme Name: My Block Theme
Theme URI: https://example.com
Author: Your Name
Description: A custom block theme built with theme.json.
Version: 1.0
Requires at least: 5.9
Tested up to: 6.5
Requires PHP: 7.4
License: GPL v2 or later
Text Domain: my-block-theme
*/

De regel Requires at least: 5.9 zorgt ervoor dat het thema werkt met de FSE-functionaliteit.

index.html

Dit is je terugvalsjabloon. Het moet beginnen met blokmarkup. Maak een eenvoudige lay-out:

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
    <!-- wp:post-title /-->
    <!-- wp:post-content /-->
</div>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

Dit gebruikt bloksyntaxis om header- en footer-sjabloondelen op te nemen en geeft de berichttitel en -inhoud weer.

Let op: Blokthema's mogen geen PHP-sjabloonbestanden bevatten zoals header.php of footer.php. Het mengen van klassieke en bloksjablonen verbreekt FSE.

Het thema activeren

Upload de map via FTP of zip-installatie en activeer het. Je zou een lege site moeten zien met je minimale structuur. Vervolgens stijlen we het met theme.json.

2. theme.json beheersen: Globale stijlen en instellingen

theme.json centraliseert alle ontwerpcontroles. Het bevindt zich in de root van je themamap. Laten we er een maken met kleur- en typografie-instellingen.

Basisstructuur

{
    "version": 2,
    "settings": {
        "color": {
            "palette": [
                {
                    "slug": "primary",
                    "color": "#007cba",
                    "name": "Primary"
                },
                {
                    "slug": "secondary",
                    "color": "#005a87",
                    "name": "Secondary"
                },
                {
                    "slug": "background",
                    "color": "#ffffff",
                    "name": "Background"
                }
            ],
            "gradients": []
        },
        "typography": {
            "fontFamilies": [
                {
                    "fontFamily": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
                    "slug": "system",
                    "name": "System"
                },
                {
                    "fontFamily": "'Georgia', serif",
                    "slug": "serif",
                    "name": "Serif"
                }
            ],
            "fontSizes": [
                {
                    "slug": "small",
                    "size": "14px",
                    "name": "Small"
                },
                {
                    "slug": "medium",
                    "size": "18px",
                    "name": "Medium"
                },
                {
                    "slug": "large",
                    "size": "24px",
                    "name": "Large"
                }
            ]
        },
        "spacing": {
            "padding": true,
            "margin": true,
            "units": ["px", "em", "rem"]
        }
    },
    "styles": {
        "color": {
            "background": "var(--wp--preset--color--background)",
            "text": "var(--wp--preset--color--primary)"
        },
        "typography": {
            "fontFamily": "var(--wp--preset--font-family--system)",
            "fontSize": "var(--wp--preset--font-size--medium)"
        }
    }
}

Dit definieert een kleurenpalet, lettertypen, lettergroottes en globale stijlen. De var()-functies verwijzen naar CSS-eigenschappen die automatisch door WordPress worden gegenereerd. Gebruikers kunnen deze vervolgens wijzigen in de Site Editor.

Tip: Gebruik CSS-eigenschappen voor consistentie. Vermijd hardcoderen van waarden in CSS-bestanden; laat theme.json de enige bron van waarheid zijn.

3. Aangepaste sjablonen maken

Bloksjablonen zijn HTML-bestanden met blokmarkup. Ze volgen een hiërarchie vergelijkbaar met klassieke sjabloonbestanden. Maak bijvoorbeeld single.html voor afzonderlijke berichten:

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
    <!-- wp:post-title {"level":1} /-->
    <!-- wp:post-featured-image /-->
    <!-- wp:post-content /-->
    <!-- wp:post-navigation-link {"type":"previous"} /-->
    <!-- wp:post-navigation-link {"type":"next"} /-->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

Maak op dezelfde manier page.html, archive.html, etc. Je kunt ook aangepaste sjablonen maken door een wp:post-template-blok toe te voegen in een query-lus.

Voor geavanceerde aanpassingen kun je overwegen om aangepaste blokken te bouwen. Leer hoe in Voorbij basisblokken: aangepaste Gutenberg-blokken maken voor verbeterde WordPress-functionaliteit.

Sjabloondelen

Maak een parts/-map voor herbruikbare onderdelen. Bijvoorbeeld header.html:

<!-- wp:group {"tagName":"header","layout":{"type":"flex","flexWrap":"nowrap"}} -->
<header class="wp-block-group">
    <!-- wp:site-logo /-->
    <!-- wp:navigation {"themeLocation":"primary"} /-->
</header>
<!-- /wp:group -->

En footer.html:

<!-- wp:paragraph {"align":"center"} -->
<p class="has-text-align-center">&copy; 2025 My Site</p>
<!-- /wp:paragraph -->

4. Blokpatronen en stijlvariaties toevoegen

Blokpatronen zijn vooraf ontworpen lay-outs. Definieer ze in een patterns/-map. Maak patterns/hero.php:

<?php
/**
 * Title: Hero
 * Slug: my-block-theme/hero
 * Categories: hero
 */
?>
<!-- wp:cover {"overlayColor":"primary","minHeight":50,"align":"full"} -->
<div class="wp-block-cover alignfull" style="min-height:50vh">
    <span aria-hidden="true" class="wp-block-cover__background has-primary-background-color"></span>
    <div class="wp-block-cover__inner-container">
        <!-- wp:heading {"textAlign":"center","level":1,"style":{"color":{"text":"#ffffff"}}} -->
        <h1 class="has-text-align-center has-text-color" style="color:#ffffff">Welkom</h1>
        <!-- /wp:heading -->
        <!-- wp:paragraph {"align":"center","textColor":"white"} -->
        <p class="has-text-align-center has-white-color">Dit is een aangepaste hero-sectie</p>
        <!-- /wp:paragraph -->
    </div>
</div>
<!-- /wp:cover -->

Stijlvariaties stellen gebruikers in staat om volledige looks te wisselen. Maak styles/default.json en styles/dark.json die thema-instellingen overschrijven.

5. Kanttekeningen en beste praktijken

• Prestaties: theme.json wordt gecacht. Verwijder de cache na wijzigingen. Gebruik de wp_register_theme_json-hook indien nodig.
• Achterwaartse compatibiliteit: Blokthema's werken alleen vanaf WordPress 5.9. Als je site oudere versies moet ondersteunen, overweeg dan een hybride aanpak maar vermijd het mengen van sjabloonbestanden.
• Kindthema's: Blokthema's kunnen worden gebruikt als bovenliggende thema's voor klassieke kindthema's, maar niet andersom. Gebruik template in style.css om een bovenliggend blokthema aan te geven.
• Internationalisering: Gebruik de __()-functie in PHP-sjabloondelen voor vertaalbare strings. Geef in blokmarkup het tekstdomein op via het textDomain-attribuut.

Voor meer over beste praktijken voor plugin-ontwikkeling, zie Robuuste WordPress-plug-ins bouwen: een praktische gids voor beste praktijken.

Conclusie

Het bouwen van een aangepast blokthema met theme.json stelt je in staat om een volledig ontwerpbare site te creëren zonder PHP aan te raken. Door deze gids te volgen, heb je een minimaal thema opgezet, globale stijlen gedefinieerd, aangepaste sjablonen gemaakt en patronen toegevoegd. Vergeet niet grondig te testen, vooral voor randgevallen zoals archiefpagina's of aangepaste berichttypen. Naarmate WordPress evolueert, worden blokthema's de standaard. Begin vandaag nog met het benutten van FSE om je workflow te stroomlijnen en klanten ongeëvenaarde flexibiliteit te bieden.

Als je het maken van thema's nog verder wilt versnellen, overweeg dan een tool die een complete site genereert uit een beschrijving. Je kunt bijvoorbeeld je gewenste lay-out beschrijven en binnen enkele minuten een gebruiksklaar blokthema hebben.

Klaar om je blokthema live te zetten? Met een beschrijving in platte tekst kun je een volledig functionele landingspagina of website genereren—geen code vereist.