Back to Details

marp-deck-gen

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Marp Deck Generator

MARP演示文稿生成工具

Purpose

用途

Assemble the final MARP deck by applying:
  • planned structure
  • finalized layout decisions
  • materialized visuals (diagrams/images)
This skill performs no planning, no interpretation, no visual design.
It is a deterministic renderer.
通过以下要素组装最终的MARP演示文稿：
  • 规划好的结构
  • 确定的布局决策
  • 已落地的视觉元素（图表/图片）
本工具不执行任何规划、解读或视觉设计工作。
它是一个确定性的渲染工具。

Inputs and outputs

输入与输出

Inputs (all mandatory)

输入（全部为必填项）

  • definition/deck-definition.md

    Semantic intent and authoritative content scope
  • planning/deck-plan.md

    Slide sequence and content intent
  • planning/deck-visual-design.md

    Authoritative layout and visual execution
If any input is missing → stop and report the error.
  • definition/deck-definition.md

    语义意图与权威内容范围
  • planning/deck-plan.md

    幻灯片顺序与内容意图
  • planning/deck-visual-design.md

    权威布局与视觉执行规范
若缺少任意一项输入 → 立即停止并上报错误。

Outputs

输出

  • slides/deck.md
    (required)
  • slides/deck-notes.md
    (required)
  • themes/deck-theme.css
    (only if a new class is explicitly required)
  • slides/deck.md
    （必填）
  • slides/deck-notes.md
    （必填）
  • themes/deck-theme.css
    （仅当明确需要新类时生成）

Required references (hard dependencies)

必需参考文件（硬依赖）

Read and follow exactly — both are mandatory:
  1. references/deck-template.md
     — the how: CSS classes, Markdown/HTML syntax, layout legality, density caps.
  2. references/brand-style-guide.md
     — the what and why: cover/section tone guidance, callout patterns, breadcrumb format, emoji rules, logo variant rules, brand color usage.
If either file cannot be found, stop immediately and report the missing file.
Do not guess or re-implement rules from either reference.
Also read: 
themes/deck-theme.css
Use it to make render-safe choices (title wrapping, density modifiers, image fit) while staying within the template's allowed classes and patterns.
必须严格阅读并遵循以下两个文件：
  1. references/deck-template.md
     — 操作规范：CSS类、Markdown/HTML语法、布局合法性、内容密度上限。
  2. references/brand-style-guide.md
     — 内容与风格规范：封面/章节语气指引、提示框样式、面包屑格式、表情符号规则、Logo变体规则、品牌色彩使用规范。
若无法找到任意一个文件，立即停止并上报缺失文件。
不得猜测或重新实现任一参考文件中的规则。
同时需阅读：
themes/deck-theme.css
在模板允许的类和模式范围内，使用该文件做出安全渲染的选择（标题换行、密度修饰符、图片适配）。

Authority and precedence rules

优先级规则

When sources conflict, apply this strict order:
  1. deck-template.md → layout legality (classes that exist; Markdown/HTML rules)
    • includes the effective behavior implied by 
      themes/deck-theme.css
  2. brand-style-guide.md → brand compliance (tone choices, callout labels, emoji, breadcrumbs)
    • cannot override what the template forbids, but constrains choices within the allowed set
  3. deck-visual-design.md → layout & visuals per slide
  4. deck-plan.md → content intent
  5. deck-definition.md → semantic boundaries
Never override a higher-priority artifact.
当源文件内容冲突时，严格按照以下顺序执行：
  1. deck-template.md → 布局合法性（已存在的类；Markdown/HTML规则）
    • 包含
      themes/deck-theme.css
      所隐含的实际行为
  2. brand-style-guide.md → 品牌合规性（语气选择、提示框标签、表情符号、面包屑）
    • 不得覆盖模板禁止的内容，但可在允许范围内限制选择
  3. deck-visual-design.md → 单张幻灯片的布局与视觉效果
  4. deck-plan.md → 内容意图
  5. deck-definition.md → 语义边界
绝不能覆盖优先级更高的工件内容。

Workflow

工作流程

1. Validate structural alignment

1. 验证结构一致性

Before rendering:
  • Slide count must match between: 
    • planning/deck-plan.md
    • planning/deck-visual-design.md
  • Slide order must be identical
  • Titles and section boundaries must align
If not → stop and report mismatch.
渲染前需确认：
  • 幻灯片数量必须与以下文件一致： 
    • planning/deck-plan.md
    • planning/deck-visual-design.md
  • 幻灯片顺序必须完全相同
  • 标题与章节边界必须对齐
若不一致 → 停止并上报不匹配问题。

2. Build deck skeleton

2. 构建演示文稿骨架

Create 
slides/deck.md
with:
  • Required MARP metadata header
  • Frontpage slide (structure unchanged; cover variant may vary)
  • Closing slide (unchanged)
Insert all user slides between frontpage and closing.
创建
slides/deck.md
文件，包含：
  • 必需的MARP元数据头部
  • 封面幻灯片（结构不变；封面变体可调整）
  • 结尾幻灯片（保持不变）
在封面与结尾幻灯片之间插入所有用户自定义幻灯片。

Cover and section style preferences

封面与章节风格偏好

Use the cover and section variant MARP class tokens exactly as listed in 
references/deck-template.md
.
Selection rules (deterministic):
  • If 
    definition/deck-definition.md
    includes an explicit preference (recommended), use it: 
    • Style preferences: cover=<name>, section=<name>
    • Example: 
      Style preferences: cover=light, section=dark
  • Else, consult 
    references/brand-style-guide.md §5
    and apply the tone guidance there without overriding it.
    • Only ask the user if the tone is still ambiguous after consulting the brand guide.
  • Apply the background selection policy in 
    references/deck-template.md
    .
严格使用
references/deck-template.md
中列出的封面和章节变体MARP类标记。
选择规则（确定性）：
  • 若
    definition/deck-definition.md
    中包含明确偏好（推荐方式），则使用该偏好：
    • 格式示例：
      Style preferences: cover=<name>, section=<name>
    • 实例：
      Style preferences: cover=light, section=dark
  • 否则，查阅
    references/brand-style-guide.md §5
    并应用其中的语气指引，不得自行修改。
    • 仅当查阅品牌指南后语气仍不明确时，方可询问用户。
  • 遵循
    references/deck-template.md
    中的背景选择策略。

3. Render slides deterministically

3. 确定性渲染幻灯片

For each slide (in order):
按顺序处理每张幻灯片：

3.1 Section slides

3.1 章节幻灯片

If the slide is a section divider:
  • Use the class comment from the section variant table (e.g. 
    <!-- _class: section dark -->
    )
  • Render only the section title as 
    # Section Title
  • Ignore visuals and content
若为章节分隔幻灯片：
  • 使用章节变体表中的类注释（例如
    <!-- _class: section dark -->
    ）
  • 仅渲染章节标题，格式为
    # Section Title
  • 忽略视觉元素与额外内容

3.2 Standard slides

3.2 标准幻灯片

For each standard slide:
  1. Layout
  • Read 
    ## Layout
    from 
    deck-visual-design.md
  • Map it to the closest valid pattern in 
    deck-template.md
  • If no valid mapping exists → stop and report
  1. Content
  • Render content strictly from 
    planning/deck-plan.md
  • Use semantic Markdown or minimal HTML
  • Respect density and structure constraints
  1. Visuals
  • If 
    ## Image
    references an asset, insert it according to the layout context.
对于每张标准幻灯片：
  1. 布局
  • 读取
    deck-visual-design.md
    中的
    ## Layout
    部分
  • 将其映射到
    deck-template.md
    中最接近的有效模式
  • 若找不到有效映射 → 停止并上报问题
  1. 内容
  • 严格从
    planning/deck-plan.md
    中渲染内容
  • 使用语义化Markdown或极简HTML
  • 遵守密度与结构限制
  1. 视觉元素
  • 若
    ## Image
    部分引用了资源，根据布局上下文插入该资源。

Slide class tokens (from visual design)

幻灯片类标记（来自视觉设计）

If 
planning/deck-visual-design.md
includes explicit slide class tokens inside 
## Layout
(e.g. 
Slide class: content visual-split image-wide no-top-accent
), render them verbatim as the slide class comment, as long as they are allowed by 
references/deck-template.md
.
If a class is requested but not supported by the template, stop and report the mismatch.
若
planning/deck-visual-design.md
的
## Layout
部分包含明确的幻灯片类标记（例如
Slide class: content visual-split image-wide no-top-accent
），只要
references/deck-template.md
允许，就直接将其作为幻灯片类注释原样渲染。
若请求的类不被模板支持，停止并上报不匹配问题。

Branded rendering patterns (brand-style-guide compliance)

品牌化渲染模式（符合品牌指南）

Apply the following patterns exactly as defined in 
references/brand-style-guide.md
:
  • Breadcrumbs → §9
  • Callout labels → §10 (class tokens from 
    references/deck-template.md
    )
  • STEP labels → §9
  • Emoji → §11
  • Closing / tagline lines → §7
严格按照
references/brand-style-guide.md
中的定义应用以下模式：
  • 面包屑 → §9
  • 提示框标签 → §10（使用
    references/deck-template.md
    中的类标记）
  • STEP标签 → §9
  • 表情符号 → §11
  • 结尾/标语行 → §7

Render-safety modifiers (allowed, deterministic)

安全渲染修饰符（允许使用，确定性）

To prevent common theme-related rendering failures (overflow, cropped visuals), it is allowed to apply these additional modifiers even if they are not explicitly listed in 
deck-visual-design.md
, as long as they are defined in 
references/deck-template.md
and 
themes/deck-theme.css
:
  • compact
    :
    • Use when slide density is too high to fit at default typography.
    • Never use it to hide content; if it still doesn’t fit, stop and report the slide as unrenderable.
  • image-wide
    / 
    image-tall
    :
    • Compute the image aspect ratio from the PNG header; apply 
      image-wide
      or 
      image-tall
      per the threshold rules in 
      references/deck-template.md
      .
    • Only apply when the slide class includes 
      visual-split
      (or another image-centric pattern where it helps fit).
Slide title length rule (mandatory): Apply the slide title length rule from 
references/deck-template.md
.
Respect the content budget hard caps defined in 
references/deck-template.md
.
When the content budget is exceeded:
  1. First reduce content (fewer bullets, shorter phrasing) — always preferred.
  2. If all content is essential, add 
    compact
    to the slide class token.
  3. If the slide still exceeds budget with 
    compact
    , stop and report the slide as unrenderable.
Use the image placement patterns and Markdown/HTML image syntax rules from 
references/deck-template.md
.
为避免常见的主题相关渲染故障（内容溢出、视觉元素被裁剪），即使
deck-visual-design.md
中未明确列出，只要
references/deck-template.md
和
themes/deck-theme.css
中定义了以下修饰符，就可应用这些修饰符：
  • compact
    :
    • 当幻灯片密度过高，默认排版无法容纳时使用。
    • 不得使用该修饰符隐藏内容；若应用后仍无法容纳，停止并上报该幻灯片无法渲染。
  • image-wide
    / 
    image-tall
    :
    • 从PNG头部计算图片宽高比；根据
      references/deck-template.md
      中的阈值规则应用
      image-wide
      或
      image-tall
      。
    • 仅当幻灯片类包含
      visual-split
      （或其他以图片为核心的模式，且该修饰符有助于适配）时应用。
幻灯片标题长度规则（强制）：遵循
references/deck-template.md
中的幻灯片标题长度规则。
遵守
references/deck-template.md
中定义的内容预算上限。
当内容超出预算时：
  1. 首先精简内容（减少项目符号、缩短措辞）——优先选择此方式。
  2. 若所有内容均为必要内容，为幻灯片类标记添加
    compact
    。
  3. 若应用
    compact
    后仍超出预算，停止并上报该幻灯片无法渲染。
使用
references/deck-template.md
中的图片放置模式和Markdown/HTML图片语法规则。

4. CSS extension (exception-only)

4. CSS扩展（仅例外情况）

Extend 
themes/deck-theme.css
only if:
  • deck-visual-design.md
    explicitly requires a layout
  • AND no existing template class can express it
Rules:
  • Minimal, reusable classes only
  • No slide-specific CSS
  • Follow CSS extension rules in the template
If extension is optional → do not add it.
仅在以下情况下扩展
themes/deck-theme.css
：
  • deck-visual-design.md
    明确要求某一布局
  • 且现有模板类无法实现该布局
规则：
  • 仅添加最小化、可复用的类
  • 不得添加幻灯片专属的CSS
  • 遵循模板中的CSS扩展规则
若扩展为可选操作 → 不得添加。

5. Generate presenter notes

5. 生成演示者备注

Create 
slides/deck-notes.md
:
  • One note block per slide
  • Same order as 
    slides/deck.md
  • Notes must:
  • Summarize slide intent
  • Provide speaking cues
  • Avoid adding new content or interpretation
Notes must remain aligned with the plan, not the visuals.
创建
slides/deck-notes.md
文件：
  • 每张幻灯片对应一个备注块
  • 顺序与
    slides/deck.md
    完全一致
  • 备注必须：
  • 总结幻灯片意图
  • 提供演讲提示
  • 不得添加新内容或解读
备注必须与规划文件保持一致，而非视觉设计文件。

Quality gates (mandatory)

质量校验门（强制要求）

Before finalizing:
  • Frontpage and closing slide structures are unchanged
  • Slide order and count match all inputs
  • Every visual reference resolves to an existing asset
  • No content appears that is not in the plan
  • No layout appears that is not allowed by the template
  • Slide density is moderate and readable
  • CSS is extended only when unavoidable
  • Vertical balance: every 
    content
    slide must have its title near the top with body content flowing immediately below. A large whitespace gap between title and content signals the wrong layout class or a structural error in the HTML — do not patch by adding filler content. Verify the class tokens match the template mapping.
  • Bottom clearance: no content element (card, tile, bullet, or table row) may be clipped at the slide bottom. If content overflows: reduce text first → then add 
    compact
    → then report as unrenderable.
  • Process-flow constraint: 
    process-flow
    slides must not contain any content below the 
    .flow-cards
    container. The baseline rail CSS extends below the card row; additional elements will overlap it or fall outside the safe area.
  • Brand compliance gate: verify all brand rules by re-reading 
    references/brand-style-guide.md
    — do not rely on any inline summary.
The output must be render-ready and deterministic.
最终定稿前需检查：
  • 封面与结尾幻灯片结构未被修改
  • 幻灯片顺序与数量与所有输入文件一致
  • 所有视觉元素引用均指向已存在的资源
  • 不存在任何未包含在规划文件中的内容
  • 不存在任何模板不允许的布局
  • 幻灯片密度适中且可读性良好
  • 仅在必要时扩展CSS
  • 垂直平衡：每张
    content
    幻灯片的标题必须靠近顶部，正文内容紧随其后。标题与内容之间的大空白意味着布局类错误或HTML结构错误——不得通过添加填充内容修复。需验证类标记是否与模板映射一致。
  • 底部留白：任何内容元素（卡片、tile、项目符号或表格行）不得在幻灯片底部被裁剪。若内容溢出：首先精简文本 → 然后添加
    compact
    → 最后上报无法渲染。
  • 流程幻灯片约束：
    process-flow
    幻灯片的
    .flow-cards
    容器下方不得包含任何内容。基线轨道CSS延伸至卡片行下方，额外元素会与轨道重叠或超出安全区域。
  • 品牌合规校验：重新阅读
    references/brand-style-guide.md
    以验证所有品牌规则——不得依赖任何内联摘要。
输出结果必须可直接渲染且具有确定性。