From 85ff8135687f26d5d4a6f9561edffa4cfc882e3d Mon Sep 17 00:00:00 2001 From: Brenno de Winter Date: Wed, 3 Jun 2026 09:55:58 +0200 Subject: [PATCH] docs: add file format specification Document the OciDeck on-disk format: Marp-compatible Markdown, project folder layout, YAML front matter (incl. TLP and base64url style profile), per-slide-type markup, image caption sidecars, special HTML comments, and the portable .ocideck package. Link it from the README. Co-Authored-By: Claude Opus 4.8 --- README.md | 8 + docs/FILE_FORMAT.md | 368 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 376 insertions(+) create mode 100644 docs/FILE_FORMAT.md diff --git a/README.md b/README.md index 3979d4b..933bf2d 100644 --- a/README.md +++ b/README.md @@ -65,6 +65,14 @@ lib/ State is managed with [Riverpod](https://riverpod.dev/). +## File format + +Presentations are saved as standard, Marp-compatible Markdown (`.md`) with a +defined project folder layout and an optional portable `.ocideck` package. The +full specification — front matter, per-slide markup, style profile, captions, +and the package format — is documented in +[`docs/FILE_FORMAT.md`](docs/FILE_FORMAT.md). + ## License All rights reserved. _(Update this section if you intend to open-source the project.)_ diff --git a/docs/FILE_FORMAT.md b/docs/FILE_FORMAT.md new file mode 100644 index 0000000..bb87f1c --- /dev/null +++ b/docs/FILE_FORMAT.md @@ -0,0 +1,368 @@ +# OciDeck — Bestandsformaat + +OciDeck slaat presentaties op als **standaard [Marp](https://marp.app/) Markdown** (`.md`). +Er is geen eigen binair formaat: een opgeslagen presentatie kan direct met de +Marp CLI of VS Code Marp-extensie verwerkt worden. OciDeck-specifieke informatie +wordt meegeschreven op manieren die Marp negeert (front-matter-sleutels en +HTML-commentaar), zodat het bestand zowel volledig Marp-compatibel is als een +verliesvrije round-trip in OciDeck oplevert. + +Daarnaast bestaan er twee afgeleide vormen: + +- een **projectmap** rond het `.md`-bestand met gekopieerde assets, en +- een **draagbaar pakket** (`.ocideck`, een zip) om een presentatie als één + bestand uit te wisselen. + +--- + +## 1. Projectmap-indeling + +Bij opslaan (`Opslaan` / `Opslaan als…`) schrijft OciDeck niet alleen de `.md`, +maar legt het ook een vaste mapstructuur ernaast aan en kopieert het alle +gebruikte assets erheen. Paden in de Markdown zijn daarna **relatief** ten +opzichte van de map van het `.md`-bestand. + +``` +mijn_presentatie/ +├── Mijn_presentatie.md # de presentatie (Marp Markdown) +├── images/ # gekopieerde afbeeldingen +│ ├── foto.png +│ └── .ocideck_captions.json # bijschriften-sidecar (zie §6) +├── logos/ # gekopieerd logo van het stijlprofiel +│ └── logo.png +├── media/ # video/audio (alleen in het pakket, zie §7) +└── themes/ + └── ocideck.css # gegenereerde thema-CSS (zie §5) +``` + +> De bestandsnaam van de `.md` wordt afgeleid van de presentatietitel: niet- +> alfanumerieke tekens worden verwijderd en spaties worden `_`. + +De mappen `images/`, `logos/`, `themes/` (en `node_modules/`, `build/`, `.git/`, +`.dart_tool/`) worden overgeslagen wanneer OciDeck een map scant op +presentaties. + +--- + +## 2. Markdown-structuur op hoofdlijnen + +```markdown +--- +marp: true +theme: ocideck +paginate: true +... (overige metadata) ... +ocideck_style_profile: +--- + + + +# Eerste slide + +--- + + + +(tweede slide) +``` + +- Het document begint met **YAML front matter** tussen `---`-regels (§3). +- Slides worden gescheiden door een regel met exact `---` (intern gesplitst op + `\n---\n`). +- Elke slide begint optioneel met een ``-regel die het + slidetype en gedrag bepaalt (§4). + +--- + +## 3. Front matter + +| Sleutel | Type | Betekenis | +| --- | --- | --- | +| `marp` | `true` | Vaste Marp-marker. | +| `theme` | string | Themanaam; standaard `ocideck`. Verwijst naar `themes/.css`. | +| `paginate` | `true`/afwezig | Wordt alleen geschreven als paginering aanstaat. | +| `author` | string | Auteur. | +| `organization` | string | Organisatie. | +| `version` | string | Versie. | +| `date` | string | Datum (vrije tekst). | +| `description` | string | Beschrijving. | +| `keywords` | string | Trefwoorden. | +| `tlp` | enum | Traffic Light Protocol-niveau (§3.1). Alleen geschreven als ≠ `none`. | +| `ocideck_style_profile` | base64url | Volledig stijlprofiel als JSON (§3.2). | + +De metadatavelden worden alleen geschreven wanneer ze niet leeg zijn. Tekst +wordt als YAML-scalar geschreven en alleen tussen dubbele quotes gezet wanneer +dat nodig is (lege waarde, rand-witruimte, of speciale tekens zoals `: # "` of +een YAML-indicator aan het begin). Bij het lezen wordt geen volwaardige +YAML-parser gebruikt maar een eenvoudige regel-voor-regel-parser; houd de front +matter dus plat (één sleutel per regel). + +### 3.1 TLP-niveaus + +Opgeslagen onder de sleutel `tlp` met deze stabiele waarden: + +| `tlp` waarde | Markering op slide | +| --- | --- | +| `none` *(niet geschreven)* | — | +| `clear` | `TLP:CLEAR` | +| `green` | `TLP:GREEN` | +| `amber` | `TLP:AMBER` | +| `amber+strict` | `TLP:AMBER+STRICT` | +| `red` | `TLP:RED` | + +### 3.2 `ocideck_style_profile` (stijlprofiel) + +Het complete visuele profiel wordt als JSON geserialiseerd, ge-UTF-8'd en +**base64url**-gecodeerd op één regel. Decodeer met base64url → UTF-8 → JSON. De +JSON heeft deze velden (met standaardwaarden): + +| Veld | Standaard | Betekenis | +| --- | --- | --- | +| `name` | `"Standaard"` | Profielnaam. | +| `slideBackgroundColor` | `#FFFFFF` | Achtergrond gewone slide. | +| `textColor` | `#222222` | Tekstkleur. | +| `accentColor` | `#2E7D64` | Accent (bullets-marker, tabelranden/-kop). | +| `tableTextColor` | = `textColor` | Tekstkleur in tabellen. | +| `tableHeaderTextColor` | `#FFFFFF` | Tekstkleur tabelkop. | +| `titleBackgroundColor` | `#1C2B47` | Achtergrond titelslide. | +| `titleTextColor` | `#FFFFFF` | Tekst op titel-/sectieslide. | +| `sectionBackgroundColor` | `#2E7D64` | Achtergrond sectieslide. | +| `logoPath` | `null` | Pad naar logo (relatief in `logos/`). | +| `logoPosition` | `bottom-right` | `top-left`/`top-right`/`bottom-left`/`bottom-right`. | +| `logoSize` | `96` | Logogrootte in px. | +| `fontFamily` | `Arial` | Lettertype van de presentatie. | +| `footerText` | `""` | Vrije footertekst; tokens: `{page}`, `{total}`, `{date}`, `{title}`. | +| `footerShowPageNumbers` | `false` | Toon "pagina / totaal" rechtsonder. | +| `footerPosition` | `right` | `left`/`center`/`right`. | + +Onbekende/ontbrekende velden vallen terug op de standaardwaarden, dus oudere +bestanden migreren probleemloos. + +--- + +## 4. Slide-classes en gedrag + +Direct na de scheiding kan een slide een class-commentaar bevatten: + +```markdown + +``` + +De eerste class bepaalt (samen met de inhoud) het **slidetype**: + +| Type | `_class` token | Detectie zonder token | +| --- | --- | --- | +| Titelpagina | `title` | — | +| Tussentitel (sectie) | `section` | — | +| Twee bulletkolommen | `two-bullets` | — | +| Bullets + afbeelding | `split` | bullets **en** afbeelding aanwezig | +| Quote | `quote` | een `>`-regel aanwezig | +| Video | `video` | een `