Authoring & project settings

Version: 0.1.0 test · c657e568. Adapted from WworPoint syntax documentation by ugas-labs, AGPL-3.0-only.

Project entry: document.md; settings: .wworpoint/project.json; styles: design/theme.css.

Markdown, metadata and section breaks

CommonMark and GFM tables, strikethrough, autolinks, static task-list checkboxes and GFM footnotes rendered as section endnotes are supported. Math, syntax highlighting and emoji shortcodes are not. Write Unicode emoji directly. CJK soft line breaks are removed next to CJK characters; otherwise they become spaces. Use a trailing backslash for a hard break.

Only the entry file may begin with YAML front matter. Supported keys: title (string), subtitle (string), author (string or string list), date (YYYY-MM-DD, never inferred), lang (BCP 47), description (string), keywords (string list). Project settings such as mode, theme, size, output, entry and security belong in project.json, not front matter. Using them there is a FRONTMATTER_PROJECT_KEY ERROR.

Presentation sections are one slide each. Top-level ---, ***, ___ or <!-- wwpo:break --> start the next slide. Put a blank line before --- to avoid a setext heading. In paged mode, only wwpo:break starts a section; --- is a horizontal rule. A paged section flows over pages, unless flow=fixed is selected. Headings never automatically split slides. Empty sections produce blank pages and an information diagnostic.

---
title: Example
author: Team
date: 2026-10-04
lang: en
---
<!-- wwpo:page layout=title -->
# A local document

---

## Next slide

<!-- wwpo:block width=70% align=center min-scale=0.7 -->
![Process](assets/diagrams/process.mmd "Local process")

Directive grammar and placement

Use a standalone top-level HTML comment: <!-- wwpo:name key=value -->. Names and keys are lowercase and case-sensitive. Quote values containing spaces or commas; escape a quote or backslash within quoted values. Directives may span lines. Nothing may follow the closing comment on that line. Inside code fences they are examples; inline or nested directives are ignored with warnings. Unknown names/keys warn; invalid values and misplaced directives are errors. wwpo:notes is reserved, not implemented.

Page settings: every supported key

Place at most one wwpo:page as the first block of the section, after front matter or a separator. Settings apply only to that section; the next resets to document.defaultPage.

Key	Supported value and behavior
size	A3, A4, A5, ISO B4, B5, JIS-B4, JIS-B5, Letter, Legal, 16:9, 4:3, or quoted width and height with mm, cm, in, pt, px
orientation	portrait or landscape; swaps dimensions when necessary
layout	Theme layout; business supports default, title, section. Unknown layout warns and falls back to default
class	Space-separated names matching [a-z][a-z0-9-]*; ps- is reserved
background	Local image path, checked like other image assets
flow	auto or fixed, paged mode only. Fixed is exactly one page; overflow is an error. In presentation mode, using flow is a DIRECTIVE_INVALID_VALUE ERROR
--name	Section CSS custom property; --ps- is reserved

B4/B5 mean ISO sizes, not Japanese JIS sizes. Explicit dimensions use their written order. 16:9 is 960×540pt and 4:3 is 720×540pt. Page geometry cannot be set by CSS; an @page size descriptor is removed with a warning. Custom property values are limited to 200 characters and refuse URLs, comments, statement delimiters, unsafe characters and unbalanced quotes; only permitted calculation and color functions are allowed. See the complete reference for the exact list.

Block attributes: every supported key

wwpo:block applies to the next top-level paragraph, figure, table, list, code block, quote or directive-produced block. A missing target warns.

Key	Value
id	[a-z][a-z0-9-]*, usable with [text](#id)
class	Space-separated classes; reserved ps- prefix
width	Percentage or length
align	left, center, right
min-scale	Figure shrink warning threshold, 0.1–1.0; default 0.7
keep	together, avoiding block splits in paged mode

Includes, images and local paths

Use <!-- wwpo:include sections/intro.md --> (quote paths with spaces). Includes must be local .md, have no front matter and no cycles. Maximum nesting is three, with 500 include occurrences and 5,000,000 total Markdown characters. Included content may contain section boundaries; diagnostics retain the included file’s own path and line number.

Relative includes/images/backgrounds resolve from the file containing the reference. Files are UTF-8, with LF or CRLF. Paths must match case exactly. Markdown includes must stay inside the project. Image assets may also use shared asset roots only when the project requests them, the machine grants them and the workspace is trusted. Hidden path segments, absolute paths and remote resource URLs are refused. Ordinary hyperlinks may point to websites; they are never fetched.

Use standard ![alt](assets/image.png "Caption"). An image alone in a paragraph becomes a figure; its optional title is the caption. PNG, JPEG, GIF, WebP, AVIF and SVG are supported with matching file contents. SVG scripts never run. Provide meaningful alt text. A data: image gives an information diagnostic; local files are preferred.

Tables and data registration

<!-- wwpo:table data=results columns="region,amount" caption="Results" --> renders registered CSV/JSON. Only data is required; columns defaults to source order. Cells retain original text and empty cells; inferred numeric columns align right. JSON tables require an array of flat objects. Unknown selected columns are errors. Long paged tables repeat headers. Markdown pipe tables also work.

A name resolves to data/results.csv or data/results.json. Alternatively, merge an explicit mapping into the existing settings, retaining the other keys:

"data": {
  "results": { "path": "data/results.csv", "encoding": "utf-8" }
}

The explicit mapping shape and utf-8 encoding were verified against the pinned schema and a real source validation.

See the A4 proposal’s actual data and source.

Mermaid and Vega-Lite

Use ![Process](assets/diagrams/process.mmd) or a mermaid fenced code block. Mermaid renders with strict security in the local export browser; diagrams cannot override security or include images/remote resources. Invalid syntax reports DIAGRAM_COMPILE_ERROR.

Use ![Results](assets/charts/results.vl.json) or a vega-lite fenced block. A minimal chart spec:

{
  "description": "Illustrative results",
  "data": { "name": "results" },
  "mark": "bar",
  "encoding": {
    "x": { "field": "region", "type": "nominal" },
    "y": { "field": "amount", "type": "quantitative" }
  }
}

data.name is the canonical form. data.url is an error; inline data.values and datasets warn. Named CSV is typed by column without filling missing values; JSON chart data is an array of records. Charts render in a separate engine process without a browser; image marks are unsupported. Invalid specs report CHART_COMPILE_ERROR. Explicit spec config/width/height override theme defaults.

Top-level fenced visuals or image-only paragraphs become fitted figures; visuals nested in text/lists/quotes are inline images. Image alt text, Mermaid accTitle, chart description/title provide accessible labels. Generated SVGs are cached under .wworpoint/generated/; they are output, not editable source. Untrusted VS Code workspaces do not render new visuals. Missing resources/browser produce warnings/placeholders where applicable.

Limits per visual: Mermaid source 50,000 characters; Vega-Lite spec 1 MiB; chart data 50,000 rows and 10 MiB; SVG 5 MiB before and 10 MiB after embedded fonts; 30 seconds per render; at most 100 visuals per document. Exceeding limits is VISUAL_LIMIT_EXCEEDED.

CSS, HTML and validation

Customize design/theme.css. Built-in classes/fonts retain ps-, PS Sans and PS Serif names. Remote CSS imports and resource loads are refused. Raw HTML is off by default; the safe subset needs both a matching project request and machine grant plus workspace trust. Scripts, style attributes, event handlers, embedded frames/forms and remote resources remain forbidden. No speaker notes, math, syntax highlighting, page-bottom footnotes or absolute coordinate positioning are implemented.

Save files, run WworPoint: Validate, resolve errors/review warnings, then WworPoint: Export. Preview can follow unsaved edits; validation/export read saved files. Source-only validation cannot establish that a page fits. AI suggestions and factual claims require human review.

Complete rules, diagnostics and examples

Complete versioned syntax reference includes the exact grammar, size dimensions, safety restrictions, diagnostic-code table and complete presentation/paged examples. Give an external AI the generated project AGENTS.md, this manual and your reviewed project sources. State that you use VS Code and want Command Palette actions; a generated guide may also show optional CLI equivalents. Do not send confidential sources without checking the provider’s terms.