SVGTreePreview

Features

• Beautiful Visuals: Generates clean, scalable SVGs with precise, connected tree lines.
• Zero-Config Icons: Automatically downloads and vectorizes Nerd Font icons (cached in ~/.config/svgtree/assets)—no font installation required for the final viewer.
• Custom Theming: Fully customizable colors, layout, and font properties via TOML.
• Font Embedding: Embed any TTF/OTF font directly into the SVG for pixel-perfect portability.
• File Preview: Embed source code highlighting and image previews directly into the tree structure.
• Smart PNG Export: High-quality rasterization using Inkscape (preferred) or CairoSVG with adjustable scaling (up to 8x).
• Modern CLI: Supports .gitignore style patterns for exclusions and respects XDG specifications for config.

Installation

Prerequisites

To build and run svgtree, you need the following dependencies. You can find package names for your specific distribution on Repology.

Dependency	Purpose	Repology Link
Python 3.8+	Core runtime	python
Cairo	PNG rendering engine	cairo
Inkscape	(Optional) Superior PNG quality	inkscape

From Source

1. Clone the repository.
2. Run the self-contained installation script (requires uv):

chmod +x install.sh
./install.sh

The script will:

1. Use uv to manage dependencies.
2. Build the project wheel.
3. Bundle svgtree into a standalone binary using shiv, targeting the system's python3 for maximum compatibility with C extensions (like Pillow).
4. Install the binary to ~/.local/bin/.
5. Deploy the default theme to ~/.config/svgtree/default-theme.toml.
6. Create the assets cache directory at ~/.config/svgtree/assets.

Usage

svgtree [ROOT_DIR] [OPTIONS]

Options

Short	Long	Description
-o	--output	Output SVG path (default: tree.svg)
-d	--depth	Max recursion depth (default: 2)
-e	--exclude	Comma-separated exclude patterns (e.g. .git, node_modules)
-s	--size	PNG scale factor from 1 to 8 (default: 1)
-p	--file-preview	Patterns to preview (e.g. *.py, logo.png)
	--png	Generate PNG output instead of SVG
	--html	Generate HTML output instead of SVG
	--theme	Path to a custom TOML theme file
-h	--help	Show all available commands

Examples

Basic scan of the current directory:

svgtree .

Preview specific files (Images and Code):

svgtree . --file-preview "*.py, logo.svg, *.png" --png

High-resolution 4x PNG with exclusions:

svgtree ~ -o home.svg -d 3 -e ".git, .cache, node_modules" --png -s 4

Using a custom theme:

svgtree . --theme ~/.config/svgtree/light-theme.toml

Theming

Themes are managed via TOML files. The tool follows the XDG specification and looks for its default theme at ~/.config/svgtree/default-theme.toml.

Here's an example of a custom theme for light mode.

# SVG Tree Theme Configuration

[colors]
# The main background color of the image
background = "#ffffff"
# Color of the tree structure lines
lines = "#9ca3af"
# Default text color for files
text_file = "#1f2937"
# Text color for folders
text_folder = "#2563eb"
# Default color for icons if not specified in [file_colors]
icon_default = "#1f2937"

[layout]
# Height of each row in pixels
row_height = 30
# Font size in pixels
font_size = 14
# Padding around the entire tree in pixels
padding = 40
# Indentation per depth level in pixels
indent_pixels = 24

[font]
# Font family string
family = "VT323"

[file_colors]
# Specific colors for file types (keys match internal type names or extensions)
folder = "#2563eb"        # Blue for folders
image = "#7c3aed"         # Purple for images
code = "#059669"          # Green for code
python = "#d97706"        # Amber for Python
js = "#d97706"            # Amber for JavaScript
html = "#dc2626"          # Red for HTML
git = "#dc2626"           # Red for Git
hidden = "#6b7280"        # Gray for hidden files
pdf = "#ea580c"           # Orange for PDFs
archive = "#0891b2"       # Cyan for archives (zip, tar, etc)
audio = "#7c3aed"         # Purple for audio
video = "#7c3aed"         # Purple for video
font = "#ea580c"          # Orange for fonts
db = "#dc2626"            # Red for databases
exec = "#dc2626"          # Red for executables (exe, bin)
text = "#1f2937"          # Dark gray for text files

The [font] section allows for advanced typography:

[font]
family = "Adwaita"
type = "Mono"
thickness = "Bold"
path = "/path/to/font.ttf"  # This will embed the font into the SVG/PNG

License

GNU General Public License v3 (GPLv3)