How it works

DWA rests on three independent layers: content, language and theme. Understanding how they are separated means understanding the whole tool.

The three layers

┌───────────────────────────────┐
│ Content    : Markdown         │  ← the author
├───────────────────────────────┤
│ Language   : Core v1 classes  │  ← stable contract (content, cols-3, color-2…)
├───────────────────────────────┤
│ Theme      : CSS (@theme …)   │  ← the organization's brand guidelines
└───────────────────────────────┘
          rendered by Marp

1. Content: Markdown

A presentation is a .md file read by Marp. Slides are separated by ---. Headings, paragraphs, lists, tables, images and blockquotes are written as they are anywhere else.

---
marp: true
theme: DWA
paginate: true
---

# First slide

---

# Second slide

2. Language: classes

Each slide gets a Marp directive that lists classes:

<!-- _class: content cols-2 cards with-title medium color-4 -->

These words are not free-form CSS: they form a closed vocabulary, Core v1, with a simple grammar (one layout, at most one composition, options). The language guide describes them all.

The _ prefix limits the directive to the current slide. Without it (class:), the directive also applies to the following slides, as Marp specifies.

3. Theme: the brand guidelines

The theme is a CSS file that declares its name (/* @theme DWA */) and implements the language's classes. It provides the colors, fonts, graphic backgrounds and dimensions (16:9, 1280 × 720 pixels for the DWA theme).

The theme name is up to you. theme: Client-A or theme: Formation work as long as the matching CSS implements Core v1. Changing the theme changes the appearance, never the structure of the Markdown.

Why classes rather than HTML?

Approach	What the author writes	Consequence
HTML/CSS in the slide	<div style="display:grid;…">	Every presentation reinvents the layout; the branding drifts.
DWA classes	content cols-3 cards	The layout is decided once, in the theme; the tooling can check it.

A closed vocabulary has another advantage: it can be verified. The extension knows that gallery-bento expects six images, that color-1 color-2 is ambiguous, or that a with-legend without a final paragraph will pick the wrong text. So it can tell you.

The journey of a slide

1. You write the directive and the content in VS Code. The extension suggests compatible classes and prefills the structure.
2. The language server analyzes the Markdown: unknown classes, ambiguous combinations, the structure expected by the composition.
3. The rendering is measured in a local Chromium, with Marp Core and the chosen CSS: text that spills out of its card is flagged.
4. You preview with Marp for VS Code, then export to HTML, PDF (Marp) or editable PowerPoint (DWA).

Where does the portal come in?

The theme portal does not touch presentations. It distributes the theme: an authorized person publishes a version, which first goes through the theme validator, and targets it at the organization or at a group. The extension of the people concerned downloads it, verifies its fingerprint and installs it once for all of VS Code: all their presentations can use it. New versions are offered unobtrusively, never forced.

What is stable, what can evolve

Core v1 fixes the public vocabulary: layouts, compositions, options, allowed values and their meaning. The exact colors, fonts, spacing and patterns belong to the theme and can evolve without changing the Markdown. A future extension of the language will add names; it will not silently change the meaning of an existing name.