Word Clouds

OKLCH-palettized word clouds generated from your GitHub starred-repo topics and languages.

Modules

scripts/word_clouds/generate.py — orchestration, file I/O, CLI-facing settings, and output dispatch
scripts/word_clouds/metaheuristic.py — animated SVG renderer that sequences 25 solver layouts into one asset

Two config models

WordCloudSettingsModel in config.py is the top-level YAML config (part of ProjectConfig). WordCloudSettings in word_clouds.py is the internal generator config with extra="forbid". Extra keys silently pass in the first, raise ValidationError in the second.

What it generates

SVG word clouds where:

Topics cloud — keywords from repositories you've starred, sorted by topic frequency
Languages cloud — programming languages across your starred repos

The README and CI pipeline default to animated SVGs where each frame is laid out by a different metaheuristic solver. Static renderers remain available for manual generation.

Input data

The word cloud reads a markdown file produced by the starred CLI tool:

.github/assets/topics.md    ← topic-grouped starred repos
.github/assets/languages.md ← language-grouped starred repos

These are updated nightly by the update-starred-lists workflow job.

CLI

# Topics word cloud
uv run python -m scripts.cli generate word-cloud \
  --config-path ./config.yaml \
  --from-topics-md \
  --output-path .github/assets/img/wordcloud_metaheuristic-anim_by_topics.svg

# Languages word cloud
uv run python -m scripts.cli generate word-cloud \
  --config-path ./config.yaml \
  --from-languages-md \
  --output-path .github/assets/img/wordcloud_metaheuristic-anim_by_languages.svg

Configuration

Under word_cloud_settings in config.yaml:

word_cloud_settings:
  output_dir: .github/assets/img
  output_filename: word_cloud.png
  prompt: "My Tech Skills: Python, JavaScript, Cloud, AI, DevOps, SQL, React"
  stopwords: []         # Additional stopwords list

Output files

File	Description
`wordcloud_metaheuristic-anim_by_topics.svg`	Animated topics cloud using 25 metaheuristic solver frames
`wordcloud_metaheuristic-anim_by_languages.svg`	Animated languages cloud using 25 metaheuristic solver frames

Rendering backends

The scripts/word_clouds/ subpackage provides several SVG renderers. The CI pipeline and README use the animated metaheuristic renderer:

Renderer	Strategy
`WordleRenderer`	Classic Wordle-style random placement
`ClusteredRenderer`	Grouped by semantic clusters
`TypographicRenderer`	Typography-focused layout
`ShapedRenderer`	Mask-based shape filling
`MetaheuristicAnimRenderer`	25 solver frames ordered into one CSS-animated SVG

Configuration

WordCloudSettingsModel reference in config.yaml

Workflows

How word clouds are generated in the CI pipeline

Configuration

Workflows

On this page