芯稿 MarkDeck 使用指南：用 Markdown 写出可编辑的 PPT

做演示文稿时，最消耗精力的往往不是写内容，而是把已经写好的标题、列表、代码、图片和表格重新复制到 PPT，再逐页调整格式。

芯稿（MarkDeck）希望把这段重复工作缩短：在 HarmonyOS PC / 2in1 上直接使用 Markdown 写作，实时查看幻灯片效果，最后导出仍可继续编辑的 .pptx。

它不是在线转换网站，也不是把页面截图塞进 PPT。文档解析、图片处理、预览和导出都在本机完成。

芯稿是什么？

芯稿是一款面向内容创作者的离线 Markdown 演示文稿工具，适合技术分享、课程讲义、项目汇报、读书笔记和个人提案。

它提供一套完整的桌面工作区：

• 左侧是幻灯片大纲：浏览、选择和调整页面顺序；
• 中间是 Markdown 编辑器：专注内容与结构；
• 右侧是实时预览：随写随看，及时发现页面溢出；
• 检查器负责样式：设置主题、强调色、页脚、页码和当前页布局；
• 导出按钮生成 PPTX：文本、表格、图片、代码和形状保持独立对象。

左侧管理页面，中间写 Markdown，右侧同步预览。

芯稿能做什么？

1. 用 Markdown 组织演示内容

芯稿支持标题、段落、粗体、斜体、删除线、行内代码、链接、三级列表、任务列表、引用、代码块、本地图片、GFM 表格和演讲者备注。

写作者不需要先学习一套复杂的幻灯片 DSL，常用 Markdown 语法就可以完成大部分内容表达。

2. 实时预览幻灯片

编辑、预览和 PPTX 导出共享同一套布局结果。内容变化后，预览会同步刷新；如果页面内容过多，芯稿会给出溢出提示，而不是无声裁掉正文。

3. 调整主题与页面布局

芯稿内置内容型、演讲型和代码型三套主题。可以统一设置文稿主题、强调色、页脚和页码，也可以单独指定某一页使用标题页、标题正文、标题列表或双栏布局。

检查器集中管理文稿样式和当前页布局。

4. 导出可继续编辑的 PPTX

导出的文件采用标准 OOXML .pptx 结构：

• 标题和正文仍是文本；
• 列表保留层级与编号；
• 表格使用原生表格对象；
• 图片可以单独移动和缩放；
• 代码保留换行、缩进和语法颜色；
• 引用装饰、页脚和页码保持为独立对象；
• 演讲者备注写入 PPTX notes page。

代码并未转成图片，导出后仍可编辑。

快速开始

1. 在文件菜单中新建文稿，或者打开本地 .md 文件。
2. 使用单独一行 --- 分隔幻灯片。
3. 在中间编辑器写内容，并在右侧检查预览。
4. 打开检查器，设置主题、强调色、页码和页面布局。
5. 点击“导出 PPTX”，处理导出检查后选择保存位置。

最小示例：

---
title: 我的第一次分享
author: Lin
theme: studio
footer: 2026 / Internal
pageNumbers: true
---

# 想法，应该直接成为演示

用 Markdown 写作，用幻灯片表达。

---

# 第二页

- 先写内容
- 实时预览
- 导出可编辑 PPTX

使用规则

下面这些规则能避免大多数解析、排版和导出问题。

规则一：文稿使用 .md 文件

芯稿以普通 Markdown 文件作为文稿源文件。Markdown 本身可以用其他文本编辑器打开，不会被锁定在应用内部。

规则二：只在文件开头使用 front matter

文件最前面的第一组 --- 会被识别为文稿设置，可填写：

---
title: 产品分享
author: Lin
theme: studio
accentColor: "#2E6CA4"
aspectRatio: 16:9
footer: 2026 / Internal
pageNumbers: true
---

theme 可使用 studio、stage 或 code。首版页面比例固定为 16:9。

front matter 结束后，其他单独成行的 --- 才表示新建一页幻灯片。不要把分页符写在代码围栏中，也不要和正文写在同一行。

规则三：一页内容从一个清晰标题开始

推荐每页使用一个 # 一级标题作为页面主题，再搭配段落、列表、图片或表格。芯稿支持 H1-H3，但一页塞入过多标题和正文会触发溢出警告。

实用原则是：一页表达一个中心信息，宁可多一页，也不要把字号压到难以阅读。

规则四：按需覆盖页面布局

不写指令时，芯稿会自动选择布局。需要明确控制时，在目标页标题前加入：

<!-- markdeck: layout=two-column -->
# 双栏页面

## 左栏

左侧内容。

## 右栏

右侧内容。

可用布局包括：

布局	适用场景
auto	让芯稿自动判断
title	封面或章节页
title-body	标题加正文
title-list	标题加要点列表
two-column	对比、并列信息

布局指令只影响它所在的页面。

规则五：图片必须使用本地相对路径

芯稿支持本地 PNG 和 JPEG，不加载远程图片、绝对路径或文稿目录外的资源。

推荐让 Markdown 和资源目录保持在一起：

产品分享.md
产品分享.assets/
  architecture.png
  demo.jpg

Markdown 中这样引用：

![系统架构](产品分享.assets/architecture.png "架构说明")

需要让照片覆盖图片区域时，可以在路径后添加 #cover：

![产品照片](产品分享.assets/demo.jpg#cover "现场演示")

直接拖入或粘贴图片时，芯稿会将图片复制到同名 .assets 目录并插入相对路径。移动文稿时，请一起移动 .md 和 .assets 目录。

规则六：备注使用 :::notes

演讲者备注写在当前页面内部：

:::notes
这一段只给演讲者看。

- 先介绍背景
- 这一页停留 60 秒
:::

备注会进入 PPTX 的原生备注页，不会显示在幻灯片画布上。每个备注块都要使用 ::: 正确闭合。

规则七：导出前先处理检查结果

点击“导出 PPTX”后，芯稿会检查页面、资源和文件结构：

• 阻断错误必须先修复，例如本地图片缺失或资源路径无效；
• 溢出警告表示内容可能超出安全区域，确认版式后才能继续；
• 取消或失败的导出不会留下损坏目标文件。

导出完成后，建议在目标办公软件中检查字体替换、链接、备注和页面边界，再进行最终分享。

常用快捷键

操作	快捷键
新建	Ctrl+N
打开 Markdown	Ctrl+O
保存	Ctrl+S
另存为	Ctrl+Shift+S
撤销 / 重做	Ctrl+Z / Ctrl+Shift+Z
查找与替换	Ctrl+F
开始放映	F5
导出 PPTX	Ctrl+Shift+E
打开帮助	F1

关于离线与文件安全

芯稿不要求登录，不提供云同步、在线 AI、广告或使用分析。Markdown 解析、预览和 PPTX 生成均在本机完成。

应用按操作访问用户选择的文档和本地图片；未保存内容的恢复副本位于应用私有目录。发现原文件被外部修改时，芯稿不会静默覆盖。

写在最后

芯稿并不试图替代所有专业演示设计工具。它更关注一条明确的创作路径：先用 Markdown 把内容写清楚，再让内容自然成为一份可以预览、放映和继续编辑的演示文稿。

• 项目主页：https://gitcode.com/VON-/MarkDeck
• 完整示例：samples/MarkDeck-MVP.md
• 使用帮助：docs/HELP.md

关键词：HarmonyOS、Markdown、PPTX、OOXML、离线办公、演示文稿、ArkUI