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[preview]" # thêm pypdfium2 để xuất ảnh PNG (`--png`, `preview`); cần cả LibreOffice
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.

Cài skill cho agent

Agent chỉ nhận đúng một file SKILL.md (thư mục skills/slidemark/), không cần đọc repo. Trang đó tự ghi lệnh cài slidemark và phần thêm cho ảnh PNG, cho HTML, nên máy chạy agent chưa cần cài gì trước.

npx skills add LeDat98/SlideMark -g                # Claude Code, Codex, Cursor… (chuẩn Agent Skills)

claude plugin marketplace add LeDat98/SlideMark    # hoặc cài dạng plugin của Claude Code
claude plugin install slidemark@slidemark

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