CodeCanvas

Lightweight Code Screenshot Beautification Engine
轻量级代码截图美化引擎 · 輕量級程式碼截圖美化工具

简体中文 · 繁體中文 · English

CodeCanvas

把代码变成精美的截图，让每一行代码都值得分享。

CodeCanvas 是一个轻量级的代码截图美化引擎，用纯 Python 编写。它能把枯燥的源代码转化为精美的、可直接用于社交媒体分享的截图。灵感来源于 carbon.now.sh 和 ray.so，但不需要 Node.js 环境，零配置即可使用。

与同类工具相比，CodeCanvas 有几个显著的不同之处：

纯 Python 实现 -- 不依赖 Node.js，Python 开发者无需额外安装运行时
零配置开箱即用 -- 安装后直接使用，所有参数都有合理默认值
内置 Web UI -- 提供可视化编辑界面，所见即所得
批量处理 -- 支持目录级别的批量渲染，适合团队文档自动化
模板系统 -- 预设配置模板，确保团队输出风格统一

✨ 核心特性

🎨 23 款内置主题

涵盖主流编辑器和社区热门配色方案，从经典到潮流一应俱全：

主题	风格	背景色
`monokai`	经典暗色	`#272822`
`dracula`	流行暗色	`#282a36`
`one-dark`	Atom 风格	`#282c34`
`github-dark`	GitHub 暗色	`#0d1117`
`github-light`	GitHub 亮色	`#ffffff`
`nord`	北极冷色调	`#2e3440`
`solarized-dark`	Solarized 暗色	`#002b36`
`solarized-light`	Solarized 亮色	`#fdf6e3`
`vs-code-dark`	VS Code Dark+	`#1e1e1e`
`vs-code-light`	VS Code Light+	`#ffffff`
`ayu-dark`	Ayu 暗色	`#0a0e14`
`ayu-light`	Ayu 亮色	`#fafafa`
`gruvbox-dark`	Gruvbox 暗色	`#282828`
`gruvbox-light`	Gruvbox 亮色	`#fbf1c7`
`tokyo-night`	东京夜色	`#1a1b26`
`catppuccin-mocha`	Catppuccin 摩卡	`#1e1e2e`
`catppuccin-latte`	Catppuccin 拿铁	`#eff1f5`
`rose-pine`	Rose Pine 暗色	`#191724`
`rose-pine-dawn`	Rose Pine 晨曦	`#faf4ed`
`night-owl`	Night Owl	`#011627`
`shades-of-purple`	紫色系	`#2d2b55`
`vitesse-dark`	Vitesse 暗色	`#121212`
`vitesse-light`	Vitesse 亮色	`#ffffff`

🪟 4 种窗口装饰风格

风格	说明
`macos`	macOS 红绿灯按钮，经典三色圆点
`windows`	Windows 风格，最小化/最大化/关闭按钮
`linux`	Linux 风格，简洁三色圆点
`none`	无窗口装饰，纯净代码展示

🔧 更多特性

500+ 语言语法高亮 -- 基于 Pygments，覆盖几乎所有编程语言
内置 Web UI -- 可视化编辑界面，实时预览效果
批量处理 -- 支持目录级别的批量渲染，自动遍历子目录
模板系统 -- 预设配置模板，团队协作风格统一
多格式导出 -- 支持 PNG / JPEG / PDF / SVG
Retina 适配 -- 支持 2x、3x 高清导出，适配 Retina 屏幕
水印支持 -- 可添加自定义水印文字
行高亮 -- 支持指定行号高亮，突出关键代码
自动语言检测 -- 根据文件扩展名或内容自动识别编程语言
剪贴板读取 -- 直接从剪贴板读取代码并渲染
零配置 -- 所有参数都有合理默认值，开箱即用

🚀 快速开始

环境要求

Python 3.8 或更高版本

安装

pip install codecanvas

基本用法

# 从文件渲染
codecanvas render main.py -o screenshot.png

# 指定主题和窗口风格
codecanvas render main.py --theme dracula --window-style macos

# 从剪贴板读取代码并渲染
codecanvas render --clipboard -o clipboard.png

# 渲染后自动复制到剪贴板
codecanvas render main.py -o screenshot.png --copy

启动 Web UI

codecanvas web
# 访问 http://127.0.0.1:8420

📖 使用指南

CLI 命令一览

CodeCanvas 提供以下子命令：

`render` -- 渲染代码截图

# 基本渲染
codecanvas render main.py -o output.png

# 完整参数示例
codecanvas render main.py \
  --theme dracula \
  --window-style macos \
  --window-title "app.py" \
  --font-size 16 \
  --font-family "JetBrains Mono" \
  --width 800 \
  --padding 40 \
  --scale 2 \
  --format png \
  --watermark "CONFIDENTIAL" \
  --highlight-lines "3,5-8,12" \
  --language python \
  -o output.png

`batch` -- 批量渲染

# 批量渲染目录下所有 Python 文件
codecanvas batch ./src --output ./screenshots

# 递归渲染，匹配多种文件类型
codecanvas batch ./src --output ./screenshots --pattern "*.py" --recursive

# 使用模板批量渲染
codecanvas batch ./src --output ./screenshots --template "team-dark"

`web` -- 启动 Web UI

# 默认启动
codecanvas web

# 指定端口，不自动打开浏览器
codecanvas web --port 9000 --no-browser

`themes` -- 主题管理

# 列出所有可用主题
codecanvas themes --list

# 查看主题详情
codecanvas themes --info dracula

`templates` -- 模板管理

# 列出所有模板
codecanvas templates --list

# 应用模板
codecanvas templates --apply "team-dark"

# 创建新模板
codecanvas templates --create "my-style"

配置选项一览

参数	说明	默认值
`--theme` / `-t`	颜色主题	`monokai`
`--background`	自定义背景色（十六进制）	主题背景色
`--padding`	内边距（像素）	`40`
`--window-style`	窗口装饰风格	`macos`
`--window-title`	窗口标题文字	文件名
`--font-size`	字体大小	`16`
`--font-family`	字体族	`JetBrains Mono`
`--width`	最大宽度（像素）	`800`
`--scale`	导出缩放倍数（Retina）	`2`
`--format`	导出格式	`png`
`--watermark`	水印文字	无
`--highlight-lines`	高亮行号（如 `3,5-8,12`）	无
`--language`	编程语言（默认自动检测）	`auto`
`--no-line-numbers`	隐藏行号	显示
`--clipboard`	从剪贴板读取	关闭
`--copy`	渲染后复制到剪贴板	关闭
`--template`	应用预设模板	无

Python API 调用

除了命令行工具，CodeCanvas 也可以作为 Python 库直接调用：

from codecanvas.renderer import CodeCanvas

# 创建渲染器实例
canvas = CodeCanvas(config={
    "theme": "dracula",
    "window_style": "macos",
    "padding": 40,
    "font_size": 16,
    "export_scale": 2,
})

# 从文件渲染
output = canvas.render_from_file("main.py", "screenshot.png")
print(f"截图已保存: {output}")

# 从字符串渲染
code = 'print("Hello, CodeCanvas!")'
output = canvas.render_from_string(code, "hello.png")

# 从剪贴板渲染
output = canvas.render_from_clipboard("clipboard.png")

🎨 主题展示

所有 23 款内置主题的效果预览存放在 examples/output/ 目录下。

📋 查看完整主题列表与背景色

主题名称	显示名称	背景色	预览
`monokai`	Monokai	`#272822`	经典 Sublime Text 配色，暖色调暗色主题
`dracula`	Dracula	`#282a36`	社区最受欢迎的暗色主题之一
`one-dark`	One Dark	`#282c34`	Atom 编辑器默认暗色主题
`github-dark`	GitHub Dark	`#0d1117`	GitHub 官方暗色模式
`github-light`	GitHub Light	`#ffffff`	GitHub 官方亮色模式
`nord`	Nord	`#2e3440`	来自北极的冷色调配色方案
`solarized-dark`	Solarized Dark	`#002b36`	Solarized 经典暗色变体
`solarized-light`	Solarized Light	`#fdf6e3`	Solarized 经典亮色变体
`vs-code-dark`	VS Code Dark+	`#1e1e1e`	Visual Studio Code 默认暗色主题
`vs-code-light`	VS Code Light+	`#ffffff`	Visual Studio Code 默认亮色主题
`ayu-dark`	Ayu Dark	`#0a0e14`	Ayu 系列暗色主题
`ayu-light`	Ayu Light	`#fafafa`	Ayu 系列亮色主题
`gruvbox-dark`	Gruvbox Dark	`#282828`	复古暖色调暗色主题
`gruvbox-light`	Gruvbox Light	`#fbf1c7`	复古暖色调亮色主题
`tokyo-night`	Tokyo Night	`#1a1b26`	灵感来自东京夜景的暗色主题
`catppuccin-mocha`	Catppuccin Mocha	`#1e1e2e`	Catppuccin 系列深色变体
`catppuccin-latte`	Catppuccin Latte	`#eff1f5`	Catppuccin 系列亮色变体
`rose-pine`	Rose Pine	`#191724`	优雅的玫瑰松暗色主题
`rose-pine-dawn`	Rose Pine Dawn	`#faf4ed`	Rose Pine 晨曦亮色变体
`night-owl`	Night Owl	`#011627`	Sarah Drasner 设计的夜猫子主题
`shades-of-purple`	Shades of Purple	`#2d2b55`	紫色系暗色主题
`vitesse-dark`	Vitesse Dark	`#121212`	Vite 生态暗色主题
`vitesse-light`	Vitesse Light	`#ffffff`	Vite 生态亮色主题

💡 设计思路

为什么选择纯 Python？

市面上主流的代码截图工具（如 Carbon）大多基于 Node.js 生态。对于 Python 开发者来说，为了一个截图工具去安装 Node.js 运行时并不划算。CodeCanvas 用纯 Python 实现，与 Python 项目的工具链无缝集成，CI/CD 流水线中也能直接调用。

为什么选择 Pillow + Pygments？

Pillow -- Python 图像处理的事实标准，成熟稳定，API 设计优雅，足以胜任代码截图的渲染需求
Pygments -- Python 语法高亮的事实标准，支持 500+ 种编程语言，词法分析准确可靠

这两个库的组合既轻量又强大，不需要 Chromium 或其他重量级依赖，安装简单、运行快速。

架构概览

codecanvas/
├── cli.py          # 命令行入口，参数解析与命令分发
├── renderer.py     # 核心渲染引擎，语法高亮与图像绘制
├── themes.py       # 主题管理系统，23 款内置主题
├── templates.py    # 模板系统，预设配置管理
├── batch.py        # 批量处理模块
├── web.py          # Web UI 服务端
└── utils.py        # 工具函数（字体查找、语言检测等）

渲染管线流程：

语法高亮 -- Pygments 对源代码进行词法分析，生成带颜色标记的 token 流
布局计算 -- 根据字体、行高、内边距等参数计算画布尺寸
背景绘制 -- 绘制圆角矩形背景，可选高斯模糊阴影
窗口装饰 -- 根据 window_style 绘制标题栏和控制按钮
代码绘制 -- 逐 token 绘制语法高亮后的代码文本
行号绘制 -- 在代码左侧绘制带对齐的行号
行高亮 -- 对指定行添加半透明高亮背景
水印叠加 -- 可选地在画面上叠加水印文字
图像导出 -- 按 PNG/JPEG/PDF/SVG 格式输出，支持 Retina 缩放

未来规划

自定义主题编辑器（Web UI 内置）
渐变背景支持
代码片段分享平台集成
VS Code / JetBrains 插件
Figma / Sketch 插件导出

📦 安装与部署

从 PyPI 安装（推荐）

pip install codecanvas

从源码安装

git clone https://github.com/gitstq/codecanvas.git
cd codecanvas
pip install -e .

安装开发依赖

pip install -e ".[dev]"

Web 服务部署

# 启动 Web UI（默认端口 8420）
codecanvas web --host 0.0.0.0 --port 8420

# 后台运行
nohup codecanvas web --host 0.0.0.0 --port 8420 --no-browser &

🤝 贡献指南

欢迎任何形式的贡献！无论是提交 Bug、改进文档还是贡献代码。

提交 Issue

使用 GitHub Issues 提交 Bug 报告或功能建议
描述问题时请附上操作系统版本、Python 版本和复现步骤

提交 PR

Fork 本仓库
创建特性分支：git checkout -b feature/your-feature
提交改动：git commit -m "feat: add your feature"
推送分支：git push origin feature/your-feature
提交 Pull Request

代码规范

遵循 PEP 8 编码规范
为新增功能编写单元测试
确保所有测试通过：pytest

📄 开源协议

本项目基于 MIT License 开源。

Copyright (c) 2024 gitstq

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

Made with ❤️ by gitstq

CodeCanvas

把程式碼變成精美的截圖，讓每一行程式碼都值得分享。

CodeCanvas 是一個輕量級的程式碼截圖美化引擎，用純 Python 撰寫。它能將枯燥的原始碼轉化為精美的、可直接用於社群媒體分享的截圖。靈感來自於 carbon.now.sh 和 ray.so，但不需要 Node.js 環境，零設定即可使用。

與同類工具相比，CodeCanvas 有幾個顯著的不同之處：

純 Python 實作 -- 不依賴 Node.js，Python 開發者無需額外安裝執行環境
零設定開箱即用 -- 安裝後直接使用，所有參數都有合理預設值
內建 Web UI -- 提供視覺化編輯介面，所見即所得
批次處理 -- 支援目錄級別的批次渲染，適合團隊文件自動化
範本系統 -- 預設配置範本，確保團隊輸出風格統一

✨ 核心特性

🎨 23 款內建主題

涵蓋主流編輯器與社群熱門配色方案，從經典到潮流一應俱全：

主題	風格	背景色
`monokai`	經典暗色	`#272822`
`dracula`	流行暗色	`#282a36`
`one-dark`	Atom 風格	`#282c34`
`github-dark`	GitHub 暗色	`#0d1117`
`github-light`	GitHub 亮色	`#ffffff`
`nord`	北極冷色調	`#2e3440`
`solarized-dark`	Solarized 暗色	`#002b36`
`solarized-light`	Solarized 亮色	`#fdf6e3`
`vs-code-dark`	VS Code Dark+	`#1e1e1e`
`vs-code-light`	VS Code Light+	`#ffffff`
`ayu-dark`	Ayu 暗色	`#0a0e14`
`ayu-light`	Ayu 亮色	`#fafafa`
`gruvbox-dark`	Gruvbox 暗色	`#282828`
`gruvbox-light`	Gruvbox 亮色	`#fbf1c7`
`tokyo-night`	東京夜色	`#1a1b26`
`catppuccin-mocha`	Catppuccin 摩卡	`#1e1e2e`
`catppuccin-latte`	Catppuccin 拿鐵	`#eff1f5`
`rose-pine`	Rose Pine 暗色	`#191724`
`rose-pine-dawn`	Rose Pine 晨曦	`#faf4ed`
`night-owl`	Night Owl	`#011627`
`shades-of-purple`	紫色系	`#2d2b55`
`vitesse-dark`	Vitesse 暗色	`#121212`
`vitesse-light`	Vitesse 亮色	`#ffffff`

🪟 4 種視窗裝飾風格

風格	說明
`macos`	macOS 紅綠燈按鈕，經典三色圓點
`windows`	Windows 風格，最小化/最大化/關閉按鈕
`linux`	Linux 風格，簡潔三色圓點
`none`	無視窗裝飾，純淨程式碼展示

🔧 更多特性

500+ 語言語法高亮 -- 基於 Pygments，涵蓋幾乎所有程式語言
內建 Web UI -- 視覺化編輯介面，即時預覽效果
批次處理 -- 支援目錄級別的批次渲染，自動遞迴子目錄
範本系統 -- 預設配置範本，團隊協作風格統一
多格式匯出 -- 支援 PNG / JPEG / PDF / SVG
Retina 适配 -- 支援 2x、3x 高清匯出，適配 Retina 螢幕
浮水印支援 -- 可新增自訂浮水印文字
行高亮 -- 支援指定行號高亮，突出關鍵程式碼
自動語言偵測 -- 根據副檔名或內容自動識別程式語言
剪貼簿讀取 -- 直接從剪貼簿讀取程式碼並渲染
零設定 -- 所有參數都有合理預設值，開箱即用

🚀 快速開始

環境需求

Python 3.8 或更高版本

安裝

pip install codecanvas

基本用法

# 從檔案渲染
codecanvas render main.py -o screenshot.png

# 指定主題和視窗風格
codecanvas render main.py --theme dracula --window-style macos

# 從剪貼簿讀取程式碼並渲染
codecanvas render --clipboard -o clipboard.png

# 渲染後自動複製到剪貼簿
codecanvas render main.py -o screenshot.png --copy

啟動 Web UI

codecanvas web
# 前往 http://127.0.0.1:8420

📖 使用指南

CLI 指令一覽

CodeCanvas 提供以下子指令：

`render` -- 渲染程式碼截圖

# 基本渲染
codecanvas render main.py -o output.png

# 完整參數範例
codecanvas render main.py \
  --theme dracula \
  --window-style macos \
  --window-title "app.py" \
  --font-size 16 \
  --font-family "JetBrains Mono" \
  --width 800 \
  --padding 40 \
  --scale 2 \
  --format png \
  --watermark "CONFIDENTIAL" \
  --highlight-lines "3,5-8,12" \
  --language python \
  -o output.png

`batch` -- 批次渲染

# 批次渲染目錄下所有 Python 檔案
codecanvas batch ./src --output ./screenshots

# 遞迴渲染，匹配多種檔案類型
codecanvas batch ./src --output ./screenshots --pattern "*.py" --recursive

# 使用範本批次渲染
codecanvas batch ./src --output ./screenshots --template "team-dark"

`web` -- 啟動 Web UI

# 預設啟動
codecanvas web

# 指定連接埠，不自動開啟瀏覽器
codecanvas web --port 9000 --no-browser

`themes` -- 主題管理

# 列出所有可用主題
codecanvas themes --list

# 查看主題詳情
codecanvas themes --info dracula

`templates` -- 範本管理

# 列出所有範本
codecanvas templates --list

# 套用範本
codecanvas templates --apply "team-dark"

# 建立新範本
codecanvas templates --create "my-style"

設定選項一覽

參數	說明	預設值
`--theme` / `-t`	顏色主題	`monokai`
`--background`	自訂背景色（十六進位）	主題背景色
`--padding`	內邊距（像素）	`40`
`--window-style`	視窗裝飾風格	`macos`
`--window-title`	視窗標題文字	檔案名稱
`--font-size`	字型大小	`16`
`--font-family`	字型族	`JetBrains Mono`
`--width`	最大寬度（像素）	`800`
`--scale`	匯出縮放倍數（Retina）	`2`
`--format`	匯出格式	`png`
`--watermark`	浮水印文字	無
`--highlight-lines`	高亮行號（如 `3,5-8,12`）	無
`--language`	程式語言（預設自動偵測）	`auto`
`--no-line-numbers`	隱藏行號	顯示
`--clipboard`	從剪貼簿讀取	關閉
`--copy`	渲染後複製到剪貼簿	關閉
`--template`	套用預設範本	無

Python API 呼叫

除了命令列工具，CodeCanvas 也可以作為 Python 函式庫直接呼叫：

from codecanvas.renderer import CodeCanvas

# 建立渲染器實例
canvas = CodeCanvas(config={
    "theme": "dracula",
    "window_style": "macos",
    "padding": 40,
    "font_size": 16,
    "export_scale": 2,
})

# 從檔案渲染
output = canvas.render_from_file("main.py", "screenshot.png")
print(f"截圖已儲存: {output}")

# 從字串渲染
code = 'print("Hello, CodeCanvas!")'
output = canvas.render_from_string(code, "hello.png")

# 從剪貼簿渲染
output = canvas.render_from_clipboard("clipboard.png")

🎨 主題展示

所有 23 款內建主題的效果預覽存放在 examples/output/ 目錄下。

📋 查看完整主題列表與背景色

主題名稱	顯示名稱	背景色	預覽
`monokai`	Monokai	`#272822`	經典 Sublime Text 配色，暖色調暗色主題
`dracula`	Dracula	`#282a36`	社群最受歡迎的暗色主題之一
`one-dark`	One Dark	`#282c34`	Atom 編輯器預設暗色主題
`github-dark`	GitHub Dark	`#0d1117`	GitHub 官方暗色模式
`github-light`	GitHub Light	`#ffffff`	GitHub 官方亮色模式
`nord`	Nord	`#2e3440`	來自北極的冷色調配色方案
`solarized-dark`	Solarized Dark	`#002b36`	Solarized 經典暗色變體
`solarized-light`	Solarized Light	`#fdf6e3`	Solarized 經典亮色變體
`vs-code-dark`	VS Code Dark+	`#1e1e1e`	Visual Studio Code 預設暗色主題
`vs-code-light`	VS Code Light+	`#ffffff`	Visual Studio Code 預設亮色主題
`ayu-dark`	Ayu Dark	`#0a0e14`	Ayu 系列暗色主題
`ayu-light`	Ayu Light	`#fafafa`	Ayu 系列亮色主題
`gruvbox-dark`	Gruvbox Dark	`#282828`	復古暖色調暗色主題
`gruvbox-light`	Gruvbox Light	`#fbf1c7`	復古暖色調亮色主題
`tokyo-night`	Tokyo Night	`#1a1b26`	靈感來自東京夜景的暗色主題
`catppuccin-mocha`	Catppuccin Mocha	`#1e1e2e`	Catppuccin 系列深色變體
`catppuccin-latte`	Catppuccin Latte	`#eff1f5`	Catppuccin 系列亮色變體
`rose-pine`	Rose Pine	`#191724`	優雅的玫瑰松暗色主題
`rose-pine-dawn`	Rose Pine Dawn	`#faf4ed`	Rose Pine 晨曦亮色變體
`night-owl`	Night Owl	`#011627`	Sarah Drasner 設計的夜貓子主題
`shades-of-purple`	Shades of Purple	`#2d2b55`	紫色系暗色主題
`vitesse-dark`	Vitesse Dark	`#121212`	Vite 生態暗色主題
`vitesse-light`	Vitesse Light	`#ffffff`	Vite 生態亮色主題

💡 設計思路

為什麼選擇純 Python？

市面上主流的程式碼截圖工具（如 Carbon）大多基於 Node.js 生態。對於 Python 開發者來說，為了一個截圖工具去安裝 Node.js 執行環境並不划算。CodeCanvas 用純 Python 實作，與 Python 專案的工具鏈無縫整合，CI/CD 流水線中也能直接呼叫。

為什麼選擇 Pillow + Pygments？

Pillow -- Python 影像處理的事實標準，成熟穩定，API 設計優雅，足以勝任程式碼截圖的渲染需求
Pygments -- Python 語法高亮的事實標準，支援 500+ 種程式語言，詞法分析準確可靠

這兩個函式庫的組合既輕量又強大，不需要 Chromium 或其他重量級依賴，安裝簡單、執行快速。

架構概覽

codecanvas/
├── cli.py          # 命令列入口，參數解析與指令分發
├── renderer.py     # 核心渲染引擎，語法高亮與影像繪製
├── themes.py       # 主題管理系統，23 款內建主題
├── templates.py    # 範本系統，預設配置管理
├── batch.py        # 批次處理模組
├── web.py          # Web UI 伺服端
└── utils.py        # 工具函式（字型查找、語言偵測等）

渲染管線流程：

語法高亮 -- Pygments 對原始碼進行詞法分析，產生帶顏色標記的 token 串流
版面計算 -- 根據字型、行高、內邊距等參數計算畫布尺寸
背景繪製 -- 繪製圓角矩形背景，可選高斯模糊陰影
視窗裝飾 -- 根據 window_style 繪製標題列和控制按鈕
程式碼繪製 -- 逐 token 繪製語法高亮後的程式碼文字
行號繪製 -- 在程式碼左側繪製帶對齊的行號
行高亮 -- 對指定行新增半透明高亮背景
浮水印疊加 -- 可選地在畫面上疊加浮水印文字
影像匯出 -- 按 PNG/JPEG/PDF/SVG 格式輸出，支援 Retina 縮放

未來規劃

自訂主題編輯器（Web UI 內建）
漸層背景支援
程式碼片段分享平台整合
VS Code / JetBrains 外掛
Figma / Sketch 外掛匯出

📦 安裝與部署

從 PyPI 安裝（推薦）

pip install codecanvas

從原始碼安裝

git clone https://github.com/gitstq/codecanvas.git
cd codecanvas
pip install -e .

安裝開發依賴

pip install -e ".[dev]"

Web 服務部署

# 啟動 Web UI（預設連接埠 8420）
codecanvas web --host 0.0.0.0 --port 8420

# 背景執行
nohup codecanvas web --host 0.0.0.0 --port 8420 --no-browser &

🤝 貢獻指南

歡迎任何形式的貢獻！無論是回報 Bug、改善文件還是貢獻程式碼。

回報 Issue

使用 GitHub Issues 回報 Bug 或提出功能建議
描述問題時請附上作業系統版本、Python 版本與重現步驟

提交 PR

Fork 本儲存庫
建立特性分支：git checkout -b feature/your-feature
提交變更：git commit -m "feat: add your feature"
推送分支：git push origin feature/your-feature
提交 Pull Request

程式碼規範

遵循 PEP 8 編碼規範
為新增功能撰寫單元測試
確保所有測試通過：pytest

📄 開源協議

本專案基於 MIT License 開源。

Copyright (c) 2024 gitstq

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

Made with ❤️ by gitstq

CodeCanvas

Turn your code into beautiful, shareable screenshots.

CodeCanvas is a lightweight code screenshot beautification engine written in pure Python. It transforms raw source code into stunning, publication-ready screenshots perfect for social media sharing. Inspired by carbon.now.sh and ray.so, but with zero Node.js dependency and zero configuration required.

What sets CodeCanvas apart from similar tools:

Pure Python -- No Node.js runtime needed, seamlessly integrates into Python workflows
Zero config -- Sensible defaults for everything, works right out of the box
Built-in Web UI -- Visual editing interface with live preview
Batch processing -- Directory-level batch rendering for documentation automation
Template system -- Predefined configuration templates for team consistency

✨ Core Features

🎨 23 Built-in Themes

A curated collection covering mainstream editors and community favorites, from timeless classics to trending palettes:

Theme	Style	Background
`monokai`	Classic Dark	`#272822`
`dracula`	Popular Dark	`#282a36`
`one-dark`	Atom Style	`#282c34`
`github-dark`	GitHub Dark	`#0d1117`
`github-light`	GitHub Light	`#ffffff`
`nord`	Arctic Cool	`#2e3440`
`solarized-dark`	Solarized Dark	`#002b36`
`solarized-light`	Solarized Light	`#fdf6e3`
`vs-code-dark`	VS Code Dark+	`#1e1e1e`
`vs-code-light`	VS Code Light+	`#ffffff`
`ayu-dark`	Ayu Dark	`#0a0e14`
`ayu-light`	Ayu Light	`#fafafa`
`gruvbox-dark`	Gruvbox Dark	`#282828`
`gruvbox-light`	Gruvbox Light	`#fbf1c7`
`tokyo-night`	Tokyo Night	`#1a1b26`
`catppuccin-mocha`	Catppuccin Mocha	`#1e1e2e`
`catppuccin-latte`	Catppuccin Latte	`#eff1f5`
`rose-pine`	Rose Pine	`#191724`
`rose-pine-dawn`	Rose Pine Dawn	`#faf4ed`
`night-owl`	Night Owl	`#011627`
`shades-of-purple`	Shades of Purple	`#2d2b55`
`vitesse-dark`	Vitesse Dark	`#121212`
`vitesse-light`	Vitesse Light	`#ffffff`

🪟 4 Window Decoration Styles

Style	Description
`macos`	macOS traffic-light buttons with classic red/yellow/green dots
`windows`	Windows-style minimize/maximize/close buttons
`linux`	Linux-style minimal three-dot buttons
`none`	No window chrome, clean code-only display

🔧 More Features

500+ language syntax highlighting -- Powered by Pygments, covering virtually every programming language
Built-in Web UI -- Visual editor with real-time preview
Batch processing -- Directory-level batch rendering with recursive traversal
Template system -- Predefined configuration templates for consistent team output
Multi-format export -- PNG / JPEG / PDF / SVG
Retina / HiDPI support -- 2x and 3x export scaling for high-DPI displays
Watermark support -- Add custom watermark text to your screenshots
Line highlighting -- Highlight specific lines to draw attention to key code
Auto language detection -- Automatically identifies the programming language from file extension or content
Clipboard support -- Read code directly from the system clipboard
Zero configuration -- Sensible defaults for all parameters, ready to use immediately

🚀 Quick Start

Requirements

Python 3.8 or later

Installation

pip install codecanvas

Basic Usage

# Render from a file
codecanvas render main.py -o screenshot.png

# Specify theme and window style
codecanvas render main.py --theme dracula --window-style macos

# Read from clipboard and render
codecanvas render --clipboard -o clipboard.png

# Copy the result back to clipboard
codecanvas render main.py -o screenshot.png --copy

Start the Web UI

codecanvas web
# Visit http://127.0.0.1:8420

📖 Usage Guide

CLI Commands

CodeCanvas provides the following subcommands:

`render` -- Render a code screenshot

# Basic render
codecanvas render main.py -o output.png

# Full parameter example
codecanvas render main.py \
  --theme dracula \
  --window-style macos \
  --window-title "app.py" \
  --font-size 16 \
  --font-family "JetBrains Mono" \
  --width 800 \
  --padding 40 \
  --scale 2 \
  --format png \
  --watermark "CONFIDENTIAL" \
  --highlight-lines "3,5-8,12" \
  --language python \
  -o output.png

`batch` -- Batch render multiple files

# Batch render all Python files in a directory
codecanvas batch ./src --output ./screenshots

# Recursive rendering with file pattern matching
codecanvas batch ./src --output ./screenshots --pattern "*.py" --recursive

# Batch render with a template
codecanvas batch ./src --output ./screenshots --template "team-dark"

`web` -- Start the Web UI

# Default launch
codecanvas web

# Custom port, no auto-open browser
codecanvas web --port 9000 --no-browser

`themes` -- Theme management

# List all available themes
codecanvas themes --list

# Show theme details
codecanvas themes --info dracula

`templates` -- Template management

# List all templates
codecanvas templates --list

# Apply a template
codecanvas templates --apply "team-dark"

# Create a new template
codecanvas templates --create "my-style"

Configuration Options

Parameter	Description	Default
`--theme` / `-t`	Color theme	`monokai`
`--background`	Custom background color (hex)	Theme background
`--padding`	Padding in pixels	`40`
`--window-style`	Window decoration style	`macos`
`--window-title`	Window title text	Filename
`--font-size`	Font size	`16`
`--font-family`	Font family	`JetBrains Mono`
`--width`	Maximum width in pixels	`800`
`--scale`	Export scale factor (Retina)	`2`
`--format`	Export format	`png`
`--watermark`	Watermark text	None
`--highlight-lines`	Lines to highlight (e.g. `3,5-8,12`)	None
`--language`	Programming language (auto-detect by default)	`auto`
`--no-line-numbers`	Hide line numbers	Show
`--clipboard`	Read from clipboard	Off
`--copy`	Copy result to clipboard after render	Off
`--template`	Apply a named template	None

Python API

Beyond the CLI, CodeCanvas can be used as a Python library:

from codecanvas.renderer import CodeCanvas

# Create a renderer instance
canvas = CodeCanvas(config={
    "theme": "dracula",
    "window_style": "macos",
    "padding": 40,
    "font_size": 16,
    "export_scale": 2,
})

# Render from a file
output = canvas.render_from_file("main.py", "screenshot.png")
print(f"Screenshot saved: {output}")

# Render from a string
code = 'print("Hello, CodeCanvas!")'
output = canvas.render_from_string(code, "hello.png")

# Render from clipboard
output = canvas.render_from_clipboard("clipboard.png")

🎨 Theme Showcase

Preview images for all 23 built-in themes are available in the examples/output/ directory.

📋 Full Theme List with Background Colors

Theme Key	Display Name	Background	Description
`monokai`	Monokai	`#272822`	Classic Sublime Text palette, warm dark theme
`dracula`	Dracula	`#282a36`	One of the most popular dark themes in the community
`one-dark`	One Dark	`#282c34`	Default dark theme from Atom editor
`github-dark`	GitHub Dark	`#0d1117`	Official GitHub dark mode
`github-light`	GitHub Light	`#ffffff`	Official GitHub light mode
`nord`	Nord	`#2e3440`	Arctic-inspired cool-toned palette
`solarized-dark`	Solarized Dark	`#002b36`	Classic Solarized dark variant
`solarized-light`	Solarized Light	`#fdf6e3`	Classic Solarized light variant
`vs-code-dark`	VS Code Dark+	`#1e1e1e`	Default dark theme from Visual Studio Code
`vs-code-light`	VS Code Light+	`#ffffff`	Default light theme from Visual Studio Code
`ayu-dark`	Ayu Dark	`#0a0e14`	Dark variant of the Ayu theme family
`ayu-light`	Ayu Light	`#fafafa`	Light variant of the Ayu theme family
`gruvbox-dark`	Gruvbox Dark	`#282828`	Retro warm-toned dark theme
`gruvbox-light`	Gruvbox Light	`#fbf1c7`	Retro warm-toned light theme
`tokyo-night`	Tokyo Night	`#1a1b26`	Dark theme inspired by the Tokyo night skyline
`catppuccin-mocha`	Catppuccin Mocha	`#1e1e2e`	Deep variant of the Catppuccin family
`catppuccin-latte`	Catppuccin Latte	`#eff1f5`	Light variant of the Catppuccin family
`rose-pine`	Rose Pine	`#191724`	Elegant rose-pine dark theme
`rose-pine-dawn`	Rose Pine Dawn	`#faf4ed`	Soft dawn variant of Rose Pine
`night-owl`	Night Owl	`#011627`	Dark theme designed by Sarah Drasner
`shades-of-purple`	Shades of Purple	`#2d2b55`	Purple-toned dark theme
`vitesse-dark`	Vitesse Dark	`#121212`	Dark theme from the Vite ecosystem
`vitesse-light`	Vitesse Light	`#ffffff`	Light theme from the Vite ecosystem

💡 Design Philosophy

Why Pure Python?

Most code screenshot tools on the market (like Carbon) are built on the Node.js ecosystem. For Python developers, installing an entire Node.js runtime just for a screenshot tool is overkill. CodeCanvas is implemented in pure Python, integrating seamlessly into Python project toolchains and CI/CD pipelines without any additional runtime.

Why Pillow + Pygments?

Pillow -- The de facto standard for image processing in Python. Mature, stable, and with an elegant API that is more than capable of handling code screenshot rendering.
Pygments -- The de facto standard for syntax highlighting in Python. Supports 500+ programming languages with accurate and reliable lexical analysis.

This combination is both lightweight and powerful. No Chromium or other heavyweight dependencies are needed -- installation is simple and rendering is fast.

Architecture Overview

codecanvas/
├── cli.py          # CLI entry point, argument parsing and command dispatch
├── renderer.py     # Core rendering engine, syntax highlighting and image drawing
├── themes.py       # Theme management system, 23 built-in themes
├── templates.py    # Template system, predefined configuration management
├── batch.py        # Batch processing module
├── web.py          # Web UI server
└── utils.py        # Utilities (font discovery, language detection, etc.)

Rendering pipeline:

Syntax highlighting -- Pygments performs lexical analysis on source code, producing a color-annotated token stream
Layout calculation -- Canvas dimensions are computed based on font, line height, padding, and other parameters
Background drawing -- Rounded rectangle background with optional Gaussian blur shadow
Window decorations -- Title bar and control buttons drawn according to window_style
Code drawing -- Syntax-highlighted code text drawn token by token
Line numbers -- Aligned line numbers drawn to the left of the code area
Line highlighting -- Semi-transparent highlight backgrounds applied to specified lines
Watermark overlay -- Optional watermark text overlaid on the canvas
Image export -- Output in PNG/JPEG/PDF/SVG format with Retina scaling support

Roadmap

Custom theme editor (built into Web UI)
Gradient background support
Code snippet sharing platform integration
VS Code / JetBrains plugin
Figma / Sketch plugin export

📦 Installation & Deployment

Install from PyPI (Recommended)

pip install codecanvas

Install from Source

git clone https://github.com/gitstq/codecanvas.git
cd codecanvas
pip install -e .

Install Development Dependencies

pip install -e ".[dev]"

Web Server Deployment

# Start the Web UI (default port 8420)
codecanvas web --host 0.0.0.0 --port 8420

# Run in the background
nohup codecanvas web --host 0.0.0.0 --port 8420 --no-browser &

🤝 Contributing

Contributions of all kinds are welcome! Whether it is filing a bug, improving documentation, or contributing code.

Filing Issues

Use GitHub Issues to submit bug reports or feature requests
When describing a problem, please include your OS version, Python version, and steps to reproduce

Submitting PRs

Fork this repository
Create a feature branch: git checkout -b feature/your-feature
Commit your changes: git commit -m "feat: add your feature"
Push the branch: git push origin feature/your-feature
Submit a Pull Request

Code Style

Follow PEP 8 conventions
Write unit tests for new features
Ensure all tests pass: pytest

📄 License

This project is released under the MIT License.

Copyright (c) 2024 gitstq

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

Made with ❤️ by gitstq

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
examples		examples
src/codecanvas		src/codecanvas
tests		tests
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
setup.py		setup.py

Folders and files

Latest commit

History

Repository files navigation

CodeCanvas

CodeCanvas

✨ 核心特性

🎨 23 款内置主题

🪟 4 种窗口装饰风格

🔧 更多特性

🚀 快速开始

环境要求

安装

基本用法

启动 Web UI

📖 使用指南

CLI 命令一览

render -- 渲染代码截图

batch -- 批量渲染

web -- 启动 Web UI

themes -- 主题管理

templates -- 模板管理

配置选项一览

Python API 调用

🎨 主题展示

💡 设计思路

为什么选择纯 Python？

为什么选择 Pillow + Pygments？

架构概览

未来规划

📦 安装与部署

从 PyPI 安装（推荐）

从源码安装

安装开发依赖

Web 服务部署

🤝 贡献指南

提交 Issue

提交 PR

代码规范

📄 开源协议

CodeCanvas

✨ 核心特性

🎨 23 款內建主題

🪟 4 種視窗裝飾風格

🔧 更多特性

🚀 快速開始

環境需求

安裝

基本用法

啟動 Web UI

📖 使用指南

CLI 指令一覽

render -- 渲染程式碼截圖

batch -- 批次渲染

web -- 啟動 Web UI

themes -- 主題管理

templates -- 範本管理

設定選項一覽

Python API 呼叫

🎨 主題展示

💡 設計思路

為什麼選擇純 Python？

為什麼選擇 Pillow + Pygments？

架構概覽

未來規劃

📦 安裝與部署

從 PyPI 安裝（推薦）

從原始碼安裝

安裝開發依賴

Web 服務部署

🤝 貢獻指南

回報 Issue

提交 PR

程式碼規範

📄 開源協議

CodeCanvas

✨ Core Features

🎨 23 Built-in Themes

🪟 4 Window Decoration Styles

🔧 More Features

`render` -- 渲染代码截图

`batch` -- 批量渲染

`web` -- 启动 Web UI

`themes` -- 主题管理

`templates` -- 模板管理

`render` -- 渲染程式碼截圖

`batch` -- 批次渲染

`web` -- 啟動 Web UI

`themes` -- 主題管理

`templates` -- 範本管理

`render` -- Render a code screenshot

`batch` -- Batch render multiple files

`web` -- Start the Web UI

`themes` -- Theme management

`templates` -- Template management

Packages