PIXELATE

a Command Line Interface (CLI) tool that generates pixel art images

Showcase • Installation • Usage • Format

🌟 Showcase

A collection of projects that use PIXELATE for their icons.

• hanson.hschang - Personal website of the author
• Persona Zola Theme - A theme for the Zola static site generator
• LaTeX Document Package - A $\LaTeX$ package for document formatting
• LaTeX Beamer Theme - A $\LaTeX$ beamer theme for presentations
• Signal-System - A Python library for Signal & System simulation, design, analysis, and learning

Want to share your project? Open a pull request!

📦 Installation

Install directly from GitHub using pip (ensure git and python >= 3.11 are installed):

pip install git+https://github.com/hanson-hschang/pixelate.git

📝 Usage

Single file usage

pixelate filename.md

This generates filename.png in the same directory as the markdown file.

Folder usage

pixelate foldername

This processes all .md files in the foldername folder and generates corresponding PNG files with the same names (e.g., pixelate.md -> pixelate.png) in the same folder.

Optional arguments

• --pixel-size SIZE: Size of each pixel in the output image (default: 10)
• --format FORMAT: Output image format (default: png)

Examples

pixelate examples/bird.md
pixelate examples/
pixelate myfile.md --pixel-size 20 --format png

🎨 Format

The Markdown File

The input markdown file consists of two parts:

1. a TOML front-matter section defining colors (both hex color codes and named color palettes), and
2. a CSV-like pixel grid where each value corresponds to a color defined in the front-matter.

+++
# TOML front-matter with color definitions
"1" = "#80808080"      # Gray with transparency
"2" = "base:m"         # Base magenta color
"3" = "tableau:blue"   # Tableau blue color
"4" = "css4:coral"     # CSS4 coral color
"5" = "xkcd:drab"      # XKCD drab color
"0" = "#00000000"      # Transparent (empty pixels)
+++

# CSV-like pixel grid (position indicates row/column)
3,5,2,5,3,0,1,1,1,1,0,0,1,1,1,1,1,0,1,0,0,0,1,0,1,1,1,1,1,0,1,0,0,0,0,0,0,1,1,1,0,0,1,1,1,1,1,0,1,1,1,1,1
5,4,5,4,5,0,1,0,0,0,1,0,0,0,1,0,0,0,0,1,0,1,0,0,1,0,0,0,0,0,1,0,0,0,0,0,1,1,0,1,1,0,0,0,1,0,0,0,1,0,0,0,0
2,5,2,5,2,0,1,1,1,1,0,0,0,0,1,0,0,0,0,0,1,0,0,0,1,1,1,1,1,0,1,0,0,0,0,0,1,0,0,0,1,0,0,0,1,0,0,0,1,1,1,1,1
5,4,5,4,5,0,1,0,0,0,0,0,0,0,1,0,0,0,0,1,0,1,0,0,1,0,0,0,0,0,1,0,0,0,0,0,1,1,1,1,1,0,0,0,1,0,0,0,1,0,0,0,0
3,5,2,5,3,0,1,0,0,0,0,0,1,1,1,1,1,0,1,0,0,0,1,0,1,1,1,1,1,0,1,1,1,1,1,0,1,0,0,0,1,0,0,0,1,0,0,0,1,1,1,1,1

Supported Named Color Palettes:

• Base colors (8 colors): base:r (red, #FF0000), base:g (green, #008000), base:b (blue, #0000FF), base:c (cyan, #00BFBF), base:m (magenta, #BF00BF), base:y (yellow, #BFBF00), base:k (black, #000000), base:w (white, #FFFFFF)

• Tableau colors (10 colors): tableau:blue, tableau:orange, tableau:green, tableau:red, tableau:purple, tableau:brown, tableau:pink, tableau:gray, tableau:olive, tableau:cyan

• CSS4 colors (139 colors): css4:red, css4:blue, css4:green, css4:aliceblue, css4:antiquewhite, css4:aqua (cyan), css4:beige, css4:coral, css4:gold, and many more standard web colors

• XKCD colors (949 colors): xkcd:red, xkcd:drab, xkcd:navy, xkcd:lime, xkcd:coral, xkcd:gold, xkcd:azure, and hundreds more from the XKCD color survey

---

⭐ Star this repository if you find it helpful!