SlideMark

Thư viện Python giúp AI Agent tạo file PowerPoint (.pptx) native, chỉnh sửa được chỉ bằng cách viết văn bản theo cú pháp riêng của SlideMark: ngắn gọn, tốn ít token và hỗ trợ cả slide dày đặc kiểu Nhật.

Trạng thái: đang phát triển (đã xong 7 ngày nền móng, đang leo các cấp L2 → L4). Mục tiêu từng cấp L1 → L7: docs/TARGETS.md.

Cài đặt

pip install slidemark            # thư viện + CLI `slidemark`
pip install "slidemark[html]"    # thêm Playwright nếu dùng khối HTML (cần `playwright install chromium`)

Dùng nhanh: viết deck.md theo cú pháp bên dưới rồi chạy slidemark build deck.md -o deck.pptx. Xem trước ảnh PNG (slidemark preview) cần LibreOffice cài sẵn trên máy.

Ví dụ

theme: jp-business
lang: ja

# 新規事業の検討状況と今後の方針
> 3つの課題を解決し、2027年度の黒字化を目指す
@aab/aac
## 現状
- 売上：12.4億円（前年比 +8%）
## 課題
- 解約率が ==2.1%== に上昇
## 施策
1. 導入テンプレートの整備
※ 出所：社内CRMデータ

• # mở slide mới, mỗi ## là một box, các box tự sắp xếp.
• @aab/aac là layout lưới viết trong 1 dòng.
• > dưới tiêu đề là thông điệp chính, dòng ※ là chú thích nguồn.

Cú pháp đầy đủ: docs/SYNTAX.md.

Tính năng chính

• Box, lưới @, KPI {.kpi}, callout > [!warn], badge [x]{.badge}, mũi tên nối @ a>b, chevron/flow.
• 10 loại biểu đồ native từ CSV (nhãn, legend, định dạng số), bảng có gộp ô, công thức toán (OMML), sơ đồ Mermaid → shape native, HTML → native (hoặc ảnh dự phòng qua Chromium).
• Theme default, midnight, jp-business hoặc template .pptx/.potx của bạn; hiệu ứng xuất hiện, chuyển slide, section.
• Thiết kế tự do: không có giao diện cố định. Theme chỉ là preset token (YAML); agent tự khai báo màu, font, cỡ chữ, bo góc, gradient, bóng đổ bằng vài dòng colors: / fonts: / sizes: / style:, bằng khối ```css (34 thuộc tính CSS → shape gốc), hoặc viết cả slide bằng HTML (@html, build deck.html) và vẫn ra shape sửa được.
• slidemark check kiểm tra tràn chữ, chồng lấn, tương phản, alt ảnh… và gợi ý cách sửa trên 1 dòng (JSON được).
• slidemark docs / skill install: tài liệu cho agent, SKILL.md ≤ 1.500 token.

pip install -e .
slidemark check deck.md && slidemark build deck.md -o deck.pptx
slidemark skill install      # cài skill cho Claude Code

Windows: slidemark preview / review --png tự tìm LibreOffice trong C:\Program Files\LibreOffice; nếu cài chỗ khác, đặt biến môi trường SLIDEMARK_SOFFICE trỏ tới soffice.exe. Build .pptx không cần LibreOffice.

So sánh với python-pptx (cùng đề, 5 / 15 / 25 slide)

Cùng một agent (Sonnet), cùng đề bài, mỗi bên chạy 1 lần, đo từ lúc nhận yêu cầu đến lúc có file .pptx đạt yêu cầu (2026-10-06). Chi tiết, mã nguồn hai bên đặt cạnh nhau và ảnh slide: docs/COMPARE.md.

Số slide	Lần gọi model (SlideMark / python-pptx)	Thời gian	Token output	Chi phí
5	4 / 8	18 s / 86 s	1,4k / 10,1k	32%
15	5 / 11	40 s / 140 s	6,7k / 18,2k	40%
25	7 / 10	70 s / 198 s	7,5k / 41,5k	32%

Thiết kế là quyết định của agent (2026-10-07)

SlideMark hỗ trợ quyết định thiết kế chứ không thay agent quyết định. Từ wave 3, SKILL.md yêu cầu agent nêu rõ lựa chọn của mình cho cả deck (colors: fonts: sizes: style: footer:) và từng slide (dạng, một điểm nhấn, ghi đè vị trí/cỡ/màu khi cần); build cảnh báo design-none / design-slide và in dòng design: colors fonts sizes style footer; 14/14 slides decided form+emphasis+values. Không có lựa chọn nào được coi là "đúng" (docs/DESIGN_REQUIRED.md, docs/DESIGN_FREEDOM.md).

Cùng đề 15 slide, giám khảo thiết kế chấm mù (Opus, cùng một vòng):

Deck	Điểm	Lần gọi	Thời gian	Chi phí	Token mã nguồn
SlideMark sau AC7 (nêu quyết định, build in bản đồ fit từng slide)	3,5 / 3,0 (2 lần chạy)	4 / 5	29 s / 39 s	29% / 35%	1,5k / 1,4k
SlideMark wave 3 (nêu quyết định, chưa có bản đồ fit)	3,5	9	90 s	61%	1,6k
SlideMark wave 2 (chỉ nội dung)	3,0	5	36 s	34%	1,3k
python-pptx	2,5 / 3,0	11	140 s	100%	5,3k

Bản đồ fit: build in một dòng cho mỗi slide (slide 2: lead + 4 kpi cards 72% of body, value 48->29pt (shrunk to fit), free 16% below) nên agent biết quyết định của mình có hiệu lực không mà không cần mở ảnh; thuộc tính bị bỏ qua báo attr-ignored kèm dạng đúng. Mục tiêu AC7–AC9 (≤ 5 lần gọi, chi phí và thời gian ≤ 50% python-pptx) đã đạt.

Toàn bộ thiết kế mà agent python-pptx tự viết (64 quyết định) nêu lại được trong SlideMark với 43% token (bench/lengthbench/t2/slidemark-ported/REPORT.md, docs/DESIGN_COVERAGE.md).

Ảnh slide mẫu (cập nhật hằng ngày)

Cập nhật: 2026-10-07 · commit 2d3e402 · tạo tự động bởi scripts/gallery.py.

Cơ bản: tiêu đề, danh sách, box, bảng, biểu đồ

Nguồn: examples/01-basics.md

Slide dày đặc kiểu Nhật (jp-business)

Nguồn: examples/02-jp-dense.md

Báo cáo tiếng Việt

Nguồn: examples/03-vi-report.md

Tiếng Nhật: KPI, badge, bảng kết quả, mũi tên nối

Nguồn: examples/04-jp-kpi.md

Tiếng Nhật: quy trình chevron + bảng, luồng phê duyệt

Nguồn: examples/05-jp-process.md

Tiếng Nhật: biểu đồ thị trường, bảng so sánh đối thủ

Nguồn: examples/06-jp-market.md

Tiếng Nhật: sơ đồ tổ chức, ma trận rủi ro

Nguồn: examples/07-jp-org.md

Tiếng Nhật: kế hoạch trung hạn, lộ trình

Nguồn: examples/08-jp-roadmap.md

Theme tối (midnight): KPI, biểu đồ, Mermaid, công thức, code

Nguồn: examples/09-midnight-tech.md

Template .pptx của người dùng, ảnh (cover crop), biểu đồ, callout

Nguồn: examples/10-template.md

Tiếng Nhật: bộ 9 slide tư vấn dày đặc (tóm tắt, KPI, tổ chức, lộ trình, rủi ro)

Nguồn: examples/11-jp-consulting.md

HTML/CSS → shape gốc (đo bằng Chromium), logo SVG, công thức

Nguồn: examples/12-html-svg-math.md

Thiết kế tự do: thương hiệu tối, gradient, bóng đổ (theme: none + token)

Nguồn: examples/13-brand-aurora.md

Thiết kế tự do: thương hiệu sáng, font serif, màu đất nung (token)

Nguồn: examples/14-brand-terracotta.md

Slide HTML toàn trang (@html) + slide SlideMark dùng chung token

Nguồn: examples/15-html-mixed.md

Tiếng Nhật: chiến lược dịch vụ, Gantt, quyết định

Nguồn: examples/16-jp-strategy.md

Thiết kế tự do bằng CSS fence: phong cách tạp chí

Nguồn: examples/17-editorial-css.md

Thiết kế tự do: thương hiệu xanh chanh

Nguồn: examples/18-brand-lime.md

Tiếng Việt: bộ tư vấn theo thương hiệu (theme: none)

Nguồn: examples/19-vi-consulting-brand.md

Tiếng Nhật: bộ 11 slide dày đặc (biểu đồ cầu, Gantt, ghi chú biểu đồ)

Nguồn: examples/20-jp-retail-dense.md

Tiếng Nhật: pitch tối thiết kế bằng CSS/HTML

Nguồn: examples/21-jp-dark-pitch.md

Tiếng Anh: kế hoạch ra mắt, chevron khớp cột bảng, ghi chú biểu đồ (hl=, note=)

Nguồn: examples/22-en-launch-plan.md

Từ vựng bố cục: @timeline, @vs, @matrix, @funnel, @pyramid, @cycle, @agenda, @statement

Nguồn: examples/23-vocabulary.md

Từ vựng bố cục 2: iconlist, quote, split, proscons, progress, harvey, heatmap, pins

Nguồn: examples/24-vocabulary-2.md

25-roundtrip-forms

Nguồn: examples/25-roundtrip-forms.md

Tài liệu

File	Nội dung
docs/SYNTAX.md	Cú pháp
docs/PLAN.md	Kế hoạch 7 ngày và quy trình chạy hằng ngày
docs/TARGETS.md	Mục tiêu L1–L7
docs/AGENT_TIPS.md	Mẹo cho Agent khi dùng thư viện
docs/LESSONS.md	Lỗi đã gặp và cách giải quyết
docs/DAILY_LOG.md	Nhật ký hằng ngày