Site Architecture & Editorial Rules

This website is a filesystem-driven MDX site built with Next.js.

There is no CMS, no database, and no runtime page generation.
All pages, navigation, widgets, and layouts are derived from the filesystem at build time.

The folder structure is the site.

Fundamental rules

• Every page is an index.mdx inside a folder
• Folders define URLs
• Frontmatter defines metadata and behavior
• Widgets are MDX fragments, not pages
• All content is statically generated

Content directory (single source of truth)

content/
├── index.mdx
│
├── nieuws/
│   ├── index.mdx
│   ├── _intro.mdx
│   ├── _widgets.mdx
│   ├── energie/
│   │   ├── index.mdx
│   │   └── _widgets.mdx
│   └── economie/
│       └── index.mdx
│
├── woningmarkt/
│   ├── index.mdx
│   └── _widgets.mdx
│
└── widgets/
    ├── _widget_news.mdx
    ├── _widget_news_titles.mdx
    ├── _widget_left_*.mdx
    ├── _widget_home_*.mdx
    └── _widget_right_*.mdx

Pages and routing
One rule only

    All routable pages live in /folder/index.mdx.

There are:

    No free-standing page files

    No alternative filenames

    No dynamic content folders

URL mapping
Filesystem path	URL
content/index.mdx	/
content/nieuws/index.mdx	/nieuws
content/nieuws/energie/index.mdx	/nieuws/energie

The filesystem hierarchy directly defines the URL hierarchy.
Page frontmatter

Each page may define metadata using frontmatter.

---
title: "Energie"
description: "Ontwikkelingen in de energiemarkt"
menu: true
icon: "Zap"
weight: 2
category: Duurzaamheid
date: 2024-11-03
image: images/energie.jpg
---

Frontmatter fields
Field	Description
title	Page title and menu label
description	SEO description
menu	Include in navigation
icon	Menu icon (Lucide)
weight	Ordering in overviews
category	Category label
date	Articles or news
image	Optional teaser image
_intro.mdx (script-only helper)

    Optional file

    Never rendered as a page

    Used only by build scripts

Purpose:

    Section introduction text

    Section icon for menus or overviews

Widgets (MDX fragments)

Widgets are MDX files rendered inside page layout panels.

They:

    Are not pages

    Have no routes

    Use the same MDX rendering pipeline as pages

Global widgets (content/widgets/)

Global widgets apply site-wide.
Placement by filename
Filename pattern	Render location
_widget_left*.mdx	Left panel
_widget_home*.mdx	Center panel
_widget_right*.mdx	Right panel
_widget_news.mdx	Center (special)
_widget_news_titles.mdx	Right (special)

Widgets are:

    Loaded server-side

    Compiled with compileMDX

    Static at runtime

Section-specific widgets (_widgets.mdx)

Any folder may contain a _widgets.mdx file.

This file defines right-panel widgets scoped to that section.
Resolution order

For a page at:

content/nieuws/energie/index.mdx

The system searches in this order:

    content/nieuws/energie/_widgets.mdx

    content/nieuws/_widgets.mdx

    Global widgets

The closest _widgets.mdx wins.
Widget scope rules

    _widgets.mdx controls right panel only

    Overrides global right widgets

    Left and center widgets remain global

This enables contextual side content without breaking layout consistency.
Homepage behavior (/)

The homepage is always:

content/index.mdx

Special behavior:

    Always loads global widgets

    Layout auto-adapts:

        one-column

        two-column

        three-column

Center panel priority

    News widget

    Home widgets

    Page content fallback

Static generation

At build time:

    The filesystem is scanned

    Every folder containing index.mdx becomes a route

    All pages are statically generated

    No filesystem access occurs at runtime

This guarantees:

    Predictable builds

    Cacheable pages

    No production I/O

Generated MDX (build scripts)

Some MDX files are generated by scripts:

    News widgets

    Section overview pages

Generated content:

    Is valid MDX

    Lives inside content/

    Is committed to the repository

    Is rendered like any other page or widget

Scripts generate MDX, not HTML.
Editorial rules
Creating pages

Do

    Always create a folder

    Always use index.mdx

    Use frontmatter consistently

Do not

    Create standalone .mdx files

    Rename index.mdx

    Create pages starting with _

Using widgets

Do

    Use _widgets.mdx for section-specific side content

    Use global widgets for reusable elements

    Keep widgets concise and focused

Do not

    Put main article content in widgets

    Use widgets for navigation

    Depend on widget ordering across sections

Frontmatter usage

Do

    Use weight for ordering

    Use category sparingly

    Use valid Lucide icon names

Do not

    Duplicate titles within the same section

    Use JSX in frontmatter

    Rely on implicit folder ordering

Images

    Use relative paths

    Optimize images before committing

    Always provide meaningful alt text

Mental model

    Folders define URLs

    index.mdx defines pages

    Widgets are MDX fragments

    Scripts generate MDX, not HTML

    Next.js renders static content only