構文の完全リファレンス（英語）

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

構文の全規則・値・診断・完全な作例を保持した英語リファレンスです。日本語の書式マニュアルと併せて利用できます。

1. Design Principles

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

---

2. Base Language

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)

2.1 CJK handling

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.

---

3. Files

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.

---

4. Front Matter

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 ... -->.

---

5. Directive Grammar

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

<!-- wwpo:page size=A4 orientation=landscape -->

5.1 Grammar

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".

5.2 Placement rules

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.

5.3 Errors

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.

5.4 Directive index

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)	—

---

6. Document Structure: Sections

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

6.1 Presentation mode: ---

# 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.

6.2 Both modes: wwpo:break

<!-- wwpo:break -->

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

6.3 Empty sections

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

---

7. wwpo:page — Section Settings

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

7.1 Placement

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.

7.2 Scope

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.

7.3 Keys

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.

7.4 Size tokens

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

<!-- 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

---

9. wwpo:include — Includes

<!-- 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.

---

10. Images and Assets

![システム構成](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.

---

11. wwpo:table — Tables from Data

<!-- 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.

---

12. Diagrams and Charts

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

12.1 Mermaid

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.

12.2 Vega-Lite

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.

12.3 Placement, alt text, failures

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.

---

13. Raw HTML

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

---

14. Not Supported in v1

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. Complete Examples

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)

---
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

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.