Skip to content

Complete syntax reference

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

All syntax rules, values, diagnostics and complete examples from the pinned syntax source. Start with the authoring manual.

plain Markdown first a document must stay readable on GitHub / in any editor
minimal custom syntax one directive form only: <!-- wwpo:... -->
explicit over implicit no layout guessing, no silent fixes
diagnosable every error points at file:line with a stable code

WworPoint syntax is invisible or harmless outside WworPoint:

Construct Seen on GitHub / plain viewers
Front matter shown as a metadata table (GitHub) or plain YAML
<!-- wwpo:... --> directives invisible (HTML comments)
--- slide separator horizontal rule
```mermaid diagrams rendered by GitHub
images rendered normally
data tables / charts from data files invisible (directive) — add a link to the data file if readers need it
includes invisible; included files are readable on their own

Feature Status
CommonMark 0.31 supported
GFM tables supported
GFM strikethrough supported
GFM autolink literals supported
GFM task lists supported (rendered as static checkboxes)
GFM footnotes supported (rendered as section endnotes in v1; page-bottom footnotes deferred)
YAML front matter supported in the entry file only (§4)
Raw HTML disabled by default (§13)
Math ($...$) not supported in v1 (rendered as literal text)
Syntax highlighting not in v1 (code blocks are rendered monospaced)
Emoji shortcodes not supported (write the Unicode character)

Japanese text needs two adjustments that CommonMark does not provide:

  1. Soft line breaks. A soft line break is removed when the character on either side of it is a CJK character (ideographs, kana, or fullwidth punctuation). Otherwise it becomes a space. This prevents stray spaces in Japanese paragraphs that are wrapped in the source:

    これは長い文章を
    途中で改行した例です。

    renders as これは長い文章を途中で改行した例です。

  2. Emphasis next to CJK punctuation. **「重要」**です is recognized as emphasis. Standard CommonMark delimiter rules reject it. It is implemented with remark-cjk-friendly (and remark-cjk-friendly-gfm-strikethrough for ~~「取消」~~です).

Hard line breaks: use a trailing backslash (\) rather than two trailing spaces, because editors often strip trailing whitespace.


Role Description
Entry file project.json → entry (default document.md). It may have front matter.
Included files Markdown files pulled in with wwpo:include. They must not have front matter.

Rules:

  • Encoding: UTF-8, with or without a BOM.
  • Line endings: LF or CRLF. They may be mixed across files.
  • Every relative path (includes, images, background images) is resolved from the file that contains the reference.

Front matter is allowed only in the entry file. It must be a YAML block at the very top of the file.

---
title: 製品提案
subtitle: 2026年度 新サービス
author: 山田 花子
date: 2026-10-01
lang: ja
description: 新サービスの提案資料
keywords: [提案, 新サービス]
---
Key Type Meaning
title string Document title. Also used as PDF Title metadata (the project name is the fallback).
subtitle string Subtitle, available to theme layouts
author string or list of strings Author(s)
date string YYYY-MM-DD Document date. It is never filled in automatically, for reproducibility.
lang BCP 47 string Overrides project.json document.lang
description string PDF Subject metadata
keywords list of strings PDF Keywords metadata

Diagnostics:

Case Code Severity
YAML syntax error FRONTMATTER_INVALID_YAML ERROR
Key not in the table and not a project key FRONTMATTER_UNKNOWN_KEY WARNING (ignored)
Key that belongs to project.json: mode, theme, size, page, output, security, entry, schemaVersion, marp FRONTMATTER_PROJECT_KEY ERROR
Front matter in an included file FRONTMATTER_IN_INCLUDE ERROR

Hint for Marp users: set the theme and page size in .wworpoint/project.json, or use <!-- wwpo:page ... -->.


All WworPoint extensions use one form: an HTML comment whose content starts with wwpo:.

<!-- wwpo:page size=A4 orientation=landscape -->
directive = "<!--" , ws , "wwpo:" , name , { ws1 , arg } , ws , "-->" ;
name = lower , { lower | digit | "-" } ;
arg = key , "=" , value
| "--" , ident , "=" , value (* CSS custom property *)
| value ; (* positional, only where defined *)
key = lower , { lower | digit | "-" } ;
ident = ( lower | upper ) , { lower | upper | digit | "-" } ;
value = bare | quoted ;
bare = bare-char , { bare-char } ; (* no whitespace, '"', '=', '<', '>' *)
quoted = '"' , { any-char-except-quote-or-backslash | '\"' | '\\' } , '"' ;
ws = { " " | "\t" | newline } ;
ws1 = ( " " | "\t" | newline ) , ws ;
  • Names and keys are case-sensitive and lowercase.
  • A directive may span several lines.
  • Values containing spaces or commas must be quoted: class="wide dark".
Rule Violation
A directive must be a block of its own, starting at the beginning of a line (indented by at most 3 spaces). Inline occurrence → DIRECTIVE_INLINE_IGNORED (WARNING)
Nothing may follow --> on the same line. CommonMark would swallow the rest of that line into the comment. DIRECTIVE_TRAILING_CONTENT (WARNING)
A directive must be at the top level of a file, not inside a list, blockquote or table. DIRECTIVE_NOT_TOP_LEVEL (WARNING, ignored)
Directives inside fenced or indented code blocks are code, not directives. —

A directive does not need blank lines around it. An HTML comment block may interrupt a paragraph and ends at the line containing -->. A blank line before and after is still recommended for readability.

Case Code Severity
Unknown directive name DIRECTIVE_UNKNOWN WARNING (ignored)
Unknown key DIRECTIVE_UNKNOWN_KEY WARNING (ignored)
Invalid value DIRECTIVE_INVALID_VALUE ERROR
Directive not allowed at this position DIRECTIVE_MISPLACED ERROR
Unsafe CSS custom property value DIRECTIVE_UNSAFE_CSS_VALUE ERROR
Directive with the pre-release prefix pstudio: (test builds) LEGACY_DIRECTIVE_IGNORED WARNING (ignored; replace it with wwpo:)

Plain HTML comments without the wwpo: prefix are ordinary comments and are ignored silently, except comments that start with the pre-release prefix pstudio:, which are reported and not run.

Directive Purpose Section
wwpo:break Start a new section §6
wwpo:page Configure the current section (page geometry, layout, class, …) §7
wwpo:block Attributes for the next block §8
wwpo:include Include another Markdown file §9
wwpo:table Render a table from named data §11
wwpo:notes Reserved (speaker notes, future) —

A document is a sequence of sections.

Mode (project.json document.mode) A section is Section separators
presentation exactly one slide (fixed page) top-level --- (thematic break), or <!-- wwpo:break -->
paged one or more flowing pages. A section always starts on a new page. <!-- wwpo:break --> only
# Title slide
---
## Second slide
- point A
- point B

Rules:

  • In presentation mode, every top-level thematic break (---, ***, ___) separates slides. Thematic breaks nested inside lists or blockquotes are not separators.

  • A blank line is required before ---. Without it, CommonMark reads the previous line as a heading (setext H2):

    Some text
    ---

    In presentation mode this produces MD_SETEXT_AMBIGUOUS (WARNING). Hint: add a blank line before --- for a slide break, or use ## heading for a heading.

  • Visible horizontal rules inside a slide are not available in presentation mode. Use a CSS border instead.

<!-- wwpo:break -->

This starts a new section. In paged mode it is the only section separator. In paged mode --- is an ordinary horizontal rule.

A section with no content (only whitespace, comments or directives) is rendered as a blank page and reported as SECTION_EMPTY (INFO).


<!-- wwpo:page size=A4 orientation=landscape layout=default class="wide" --accent="#c00000" -->

wwpo:page must be the first block of a section:

  • at the start of the document (after front matter), or
  • immediately after a section separator (--- in presentation mode, or wwpo:break).

Anywhere else it produces DIRECTIVE_MISPLACED (ERROR). Hint: insert <!-- wwpo:break --> before it.

At most one wwpo:page is allowed per section.

The settings apply only to that section. The next section starts again from the document defaults (project.json document.defaultPage). In paged mode, the settings apply to every page of that section.

Key Values Modes Meaning
size size token (§7.4) or "<w> <h>" both Page size
orientation portrait | landscape both Orientation. It swaps width and height when needed, including for explicit sizes.
layout theme layout name both Theme layout, e.g. default, title, section (business theme). Unknown → THEME_LAYOUT_UNKNOWN (WARNING), then default.
class space-separated class names both Extra CSS classes on the section. Each class must match [a-z][a-z0-9-]*. The ps- prefix is reserved.
background project-relative image path both Background image, validated like any image (§10).
flow auto | fixed paged fixed = exactly one page; overflow is LAYOUT_FIXED_SECTION_OVERFLOW (ERROR). In presentation mode every section is already fixed, so flow there is DIRECTIVE_INVALID_VALUE.
--<name> CSS value both CSS custom property set on the section

Custom property values must not contain url(, ;, {, }, <, >, \, @, comments (/*) or unbalanced quotes, may call only var(), calc(), min(), max(), clamp() and color functions (rgb(), hsl(), color-mix(), …), and must be at most 200 characters long. Otherwise the result is DIRECTIVE_UNSAFE_CSS_VALUE (ERROR). Custom properties starting with --ps- are reserved.

Token Size Default orientation
A3, A4, A5 ISO 216 portrait
B4, B5 ISO B series (250×353mm, 176×250mm) portrait
JIS-B4, JIS-B5 JIS B series (257×364mm, 182×257mm) portrait
Letter, Legal 8.5×11in, 8.5×14in portrait
16:9 13.333in × 7.5in (960pt × 540pt) landscape
4:3 10in × 7.5in (720pt × 540pt) landscape
"<w> <h>" lengths in mm, cm, in, pt, px as given

Note: in Japan “B5” usually means JIS-B5 (182×257mm). Plain B5 is the ISO size.

Page geometry cannot be set from CSS. A size descriptor in an @page rule is removed with CSS_PAGE_SIZE_IGNORED (WARNING).


8. wwpo:block — Attributes for the Next Block

Section titled “8. wwpo:block — Attributes for the Next Block”
<!-- wwpo:block width=60% align=center min-scale=0.6 -->
![構成図](assets/images/architecture.svg)

It applies to the next top-level block (paragraph, figure, table, list, code block, blockquote, or a block produced by another directive). If no block follows before the next section separator or the end of the file, the result is BLOCK_DIRECTIVE_NO_TARGET (WARNING).

Key Values Meaning
id [a-z][a-z0-9-]* Anchor id, usable as a link target [see](#id)
class space-separated class names Extra CSS classes (ps- prefix reserved)
width <n>% or a length Block width
align left | center | right Horizontal alignment
min-scale number 0.1–1.0 Figures only: warning threshold for automatic shrinking (default 0.7, LAYOUT_FIGURE_SHRUNK). The scale is the displayed size relative to the size the figure would have without being fitted to its page or slide.
keep together Paged mode: avoid splitting this block across pages

<!-- wwpo:include sections/intro.md -->
<!-- wwpo:include "sections/市場 分析.md" -->

The path is a positional argument. Quote it if it contains spaces.

Rules:

Rule Violation
Target is a .md file inside the project INCLUDE_NOT_MARKDOWN / PATH_OUTSIDE_PROJECT (ERROR)
Target exists (exact case) INCLUDE_NOT_FOUND / PATH_CASE_MISMATCH (ERROR)
Nesting depth ≤ 3 INCLUDE_DEPTH_EXCEEDED (ERROR)
At most 500 includes per document (each occurrence counts) and 5,000,000 characters of Markdown in all INCLUDE_LIMIT_EXCEEDED (ERROR)
Not a hidden file or in a hidden folder (a path segment starting with .) PATH_HIDDEN (ERROR)
No cycles INCLUDE_CYCLE (ERROR)
Included file has no front matter FRONTMATTER_IN_INCLUDE (ERROR)

Behavior:

  • The include directive is replaced by the included file’s top-level content.
  • Included files may contain section separators, wwpo:page at the start of their own sections, and any other directive.
  • Diagnostics inside included content report the included file’s own path and line numbers.

![システム構成](assets/images/architecture.svg "図1 システム構成")

Rules:

  • Standard Markdown image syntax is used.
  • An image that is the only content of a paragraph is rendered as a figure. Its title, if present, becomes the caption.
  • The path is relative to the Markdown file, must stay inside the project (or granted shared roots), and must match the file’s case exactly.
  • File names are compared NFC-normalized, so Japanese file names work on macOS as well.
  • SVG files are displayed as images. Scripts inside them never run.
  • Images are PNG, JPEG, GIF, WebP, AVIF or SVG files (and, with image syntax, Mermaid .mmd and Vega-Lite .vl.json sources, §12). The file’s content must be what its extension says: exports embed it.
  • Hidden files and files in hidden folders (.git, .env, .wworpoint, any path segment starting with .) are never read as content, here or in CSS, includes and data: they often hold credentials and local settings.
Case Code Severity
File not found ASSET_NOT_FOUND ERROR
Remote URL (http:, https:, //host) ASSET_REMOTE_URL ERROR
Absolute path or file: URL PATH_ABSOLUTE ERROR
Outside the project PATH_OUTSIDE_PROJECT ERROR
Case differs from the file on disk PATH_CASE_MISMATCH ERROR
Hidden file or in a hidden folder PATH_HIDDEN ERROR
Not an image (by extension), or the content does not match the extension ASSET_NOT_ALLOWED ERROR
data: URI image ASSET_DATA_URI INFO (prefer a file under assets/)
Empty alt text ASSET_ALT_MISSING INFO

Remote images must first be imported into the project.

Hyperlinks ([text](https://example.com)) are fine. They are never fetched.


<!-- wwpo:table data=sales columns="region,q1,q2,q3,q4" caption="表1 地域別売上" -->
Key Required Meaning
data yes Data name: sales → data/sales.csv or data/sales.json, or an explicit mapping in project.json
columns no Comma-separated column names, in display order. Default: all columns in source order.
caption no Table caption

Rules:

  • Cells show the original text from the data file. Values are never reformatted or filled in. Empty cells stay empty.
  • Columns whose inferred type is numeric are right-aligned (class ps-num).
  • JSON data must be an array of flat objects. Anything else is DATA_TABLE_UNSUPPORTED_SHAPE (ERROR).
  • An unknown column in columns is DATA_COLUMN_NOT_FOUND (ERROR).
  • Long tables paginate in paged mode, with the header repeated.

Ordinary GFM pipe tables written directly in Markdown are also supported.


Diagrams (Mermaid) and charts (Vega-Lite) are written as text and rendered to SVG.

Inline (also rendered by GitHub):

```mermaid
flowchart LR
accTitle: 処理の流れ
A[入力] --> B[処理] --> C[出力]
```

From a file:

![処理フロー](assets/diagrams/flow.mmd)
  • Mermaid renders in the export browser (Chrome or Edge, like layout and export) with securityLevel: "strict", the theme’s font and colors, and labels as SVG text. A diagram cannot change the security level.
  • Diagrams show no images and load nothing: an image in a diagram (img: shapes, <img> labels) is DIAGRAM_COMPILE_ERROR.
  • A syntax error is DIAGRAM_COMPILE_ERROR at the line Mermaid names, in the Markdown file or the .mmd file.

From a file (recommended):

![売上推移](assets/charts/sales.vl.json)

Inline:

```vega-lite
{ "data": { "name": "sales" }, "mark": "bar",
"encoding": { "x": { "field": "region" }, "y": { "field": "amount", "type": "quantitative" } } }
```

Chart data rules:

Case Code Severity
data.name refers to named data (§11, the project settings) — OK (the only canonical form)
data.url CHART_DATA_URL_FORBIDDEN ERROR
inline data.values, or datasets CHART_INLINE_DATA WARNING
  • Named data is read like wwpo:table data: CSV values are typed by their column (integer, number, boolean), empty cells stay empty, and charts never fill in missing values. JSON data must be an array of records.
  • Charts render in a separate Node.js process, without a browser. Expressions (calculate, filter) work; image marks are not supported. Invalid JSON, an unknown mark type and anything Vega-Lite rejects are CHART_COMPILE_ERROR.
  • The theme sets the font, text sizes, colors and a default plot size; the spec’s config and width / height win.
Source Shown as
A top-level fenced block, or a .mmd / .vl.json image alone in its paragraph A figure (§10): fitted to the slide or page, wwpo:block attributes, the image title as caption, layout validation of its scale
A fenced block inside a list or quote, or a .mmd / .vl.json image inside text An inline image
  • Alt text: the image’s alt text; for a fenced block, Mermaid’s accTitle, else the chart’s description, else its title.
  • The rendered SVG is kept in .wworpoint/generated/diagrams/ and .wworpoint/generated/charts/ (named by a hash of the source, its data, the renderer and the theme) and reused while nothing changed, after the same safety checks as a newly rendered SVG. It is generated, never canonical; clean removes it.
  • When a diagram or chart cannot be rendered, a placeholder is shown and the reason is reported: VISUAL_PROVIDER_UNAVAILABLE (WARNING) without the export browser (diagrams; also validate --skip-layout), without the tool resources, or in an untrusted VS Code workspace, where nothing is rendered and only SVG generated before is shown; the compile errors above otherwise.
  • Each diagram or chart has resource limits: Mermaid source 50,000 characters, Vega-Lite spec 1 MiB, chart data 50,000 rows and 10 MiB, generated SVG 5 MiB before and 10 MiB after its fonts are embedded, 30 seconds to render, and at most 100 diagrams and charts per document. Exceeding one is VISUAL_LIMIT_EXCEEDED (ERROR) with the measure and the limit; the diagram or chart is a placeholder.

Setting Behavior
Default (security.html: "none") HTML blocks and inline HTML are dropped: HTML_RAW_DISABLED (WARNING) per occurrence. wwpo: directives and plain comments are not affected.
security.html: "safe-subset" and a host grant and a trusted workspace The allow-listed elements and attributes are kept. Anything else is dropped: HTML_ELEMENT_NOT_ALLOWED (WARNING).

The following are never allowed, in any mode:

<script>, <style>, style="", on*="", <iframe>, <object>, <embed>, <link>, <meta>, <base>, <form>,
remote URLs of any kind

Feature Status
Absolute / coordinate positioning deferred
Speaker notes reserved: wwpo:notes
Math deferred
Syntax highlighting deferred
Page-bottom footnotes deferred (v1: section endnotes)
Automatic slide split by headings not planned for v1 (use ---)
Marp directives (<!-- _class: -->, ![bg]) not supported. Use wwpo:page (class, background).

15.1 Presentation (document.mode: "presentation", default 16:9)

Section titled “15.1 Presentation (document.mode: "presentation", default 16:9)”
---
title: 製品提案
author: 山田 花子
date: 2026-10-01
---
<!-- wwpo:page layout=title -->
# 製品提案
2026年10月
---
## 現状の課題
- 手作業による処理
- 長いリードタイム
- 人為的ミス
---
<!-- wwpo:page layout=section background=assets/images/cover.jpg -->
## 解決策
---
## システム構成
<!-- wwpo:block width=80% align=center -->
![システム構成](assets/images/architecture.svg "図1 システム構成")
---
<!-- wwpo:include sections/details.md -->

This produces five slides from the entry file, plus any slides in sections/details.md.

15.2 Paged document (document.mode: "paged", default A4 portrait)

Section titled “15.2 Paged document (document.mode: "paged", default A4 portrait)”
---
title: 年次報告書 2026
lang: ja
---
<!-- wwpo:page layout=title flow=fixed -->
# 年次報告書 2026
株式会社サンプル
<!-- wwpo:break -->
## 1. 概要
<!-- wwpo:include sections/summary.md -->
## 2. 売上実績
<!-- wwpo:table data=sales columns="region,q1,q2,q3,q4" caption="表1 地域別売上" -->
---
上の `---` は通常の水平線として表示されます(paged モード)。
<!-- wwpo:break -->
<!-- wwpo:page orientation=landscape -->
## 付録A 詳細データ
<!-- wwpo:table data=sales-detail -->
<!-- wwpo:break -->
## 付録B 用語集
(この節は既定の A4 縦に戻ります)

Sections:

  1. Title page: A4 portrait, exactly one page.
  2. Body: A4 portrait, flowing.
  3. Appendix A: A4 landscape, flowing. The table header repeats on each page.
  4. Appendix B: A4 portrait, flowing.

16. Diagnostic Codes Used in This Document

Section titled “16. Diagnostic Codes Used in This Document”

FRONTMATTER_INVALID_YAML, FRONTMATTER_UNKNOWN_KEY, FRONTMATTER_PROJECT_KEY, FRONTMATTER_IN_INCLUDE, DIRECTIVE_UNKNOWN, DIRECTIVE_UNKNOWN_KEY, DIRECTIVE_INVALID_VALUE, DIRECTIVE_MISPLACED, DIRECTIVE_NOT_TOP_LEVEL, DIRECTIVE_INLINE_IGNORED, DIRECTIVE_TRAILING_CONTENT, DIRECTIVE_UNSAFE_CSS_VALUE, BLOCK_DIRECTIVE_NO_TARGET, MD_SETEXT_AMBIGUOUS, SECTION_EMPTY, THEME_LAYOUT_UNKNOWN, INCLUDE_NOT_FOUND, INCLUDE_NOT_MARKDOWN, INCLUDE_CYCLE, INCLUDE_DEPTH_EXCEEDED, INCLUDE_LIMIT_EXCEEDED, ASSET_NOT_FOUND, ASSET_REMOTE_URL, ASSET_DATA_URI, ASSET_ALT_MISSING, ASSET_NOT_ALLOWED, PATH_ABSOLUTE, PATH_OUTSIDE_PROJECT, PATH_CASE_MISMATCH, PATH_HIDDEN, DATA_TABLE_UNSUPPORTED_SHAPE, DATA_COLUMN_NOT_FOUND, CHART_DATA_URL_FORBIDDEN, CHART_INLINE_DATA, VISUAL_PROVIDER_UNAVAILABLE, VISUAL_LIMIT_EXCEEDED, HTML_RAW_DISABLED, HTML_ELEMENT_NOT_ALLOWED, CSS_PAGE_SIZE_IGNORED, LAYOUT_FIGURE_SHRUNK, LAYOUT_FIXED_SECTION_OVERFLOW.

Website editorial note: ERROR blocks export; WARNING requires review; INFO is informational.