DEV Community: Igor Braz

GitAscii vs github-readme-stats: Moving from Query Strings to Edge Rendering 🚀

Igor Braz — Tue, 11 Aug 2026 18:58:10 +0000

The classic github-readme-stats has been the undisputed king of profile customization for years. We have all seen the familiar stats cards pinned to thousands of developer portfolios. But relying on query parameters appended directly to an image tag introduces structural bottlenecks when you want true creative freedom and optimal load performance.

In this deep dive, we will analyze the limitations of query-string-based configurations, compare the request lifecycle of legacy card layouts against modern edge-rendered unified canvases, and look at how decoupling style from content yields superior render times and layout flexibility.

The Limitations of Query-String Architectures

Under the legacy approach of github-readme-stats, every visual tweak—such as colors, layout types, icons, and hidden sections—requires editing the URL parameters directly within the markdown content. A typical setup looks like this:

<!-- Traditional query-string approach -->

![My GitHub Stats](https://github-readme-stats.vercel.app/api?username=anuraghazra&show_icons=true&theme=radical&hide=contribs,prs&custom_title=My%20Stats&title_color=fff&icon_color=f00&text_color=000&bg_color=fff)

While this appears convenient for single cards, it introduces major architectural issues when scaling up a developer profile:

URI Length Limits (RFC 7230 & RFC 3986): Standard web servers, proxies, and CDNs enforce limits on URI length (often capped at 2,048 or 8,192 characters). If you want an editorial dashboard with precise typography, custom spacing, multiple layout sections, and color configurations, your URL quickly balloons to unmanageable sizes, risking truncated requests.
Tight Coupling (Content vs. Presentation): Changing the style (e.g., swapping a theme from light to dark or aligning elements) forces you to rewrite the code in your repository's README.md. Your content delivery layer is directly coupled to your layout presentation.
Waterfall Latency Bottlenecks: When you stack multiple cards (e.g., stats, top languages, and typing SVGs), the browser must make multiple independent connections to backend servers. Each connection triggers a separate TLS handshake and request-response loop, producing a noticeable page loading waterfall.

[!WARNING]
Stacking 3 to 5 independent server-rendered SVG badges on a single README page can increase the page's cumulative layout shift (CLS) and aggregate load times, especially under constrained mobile networks where concurrent TCP connections are limited.

The GitAscii Paradigm Shift

With GitAscii, we decoupled the user layout configuration from the content URL. Instead of packing visual parameters into query strings, we store a structured JSON design schema in a database and expose a clean, static, visual editor.

The markdown in your GitHub README remains simple, clean, and never needs to change when you edit your layout:

<!-- Decoupled GitAscii Canvas -->

[![GitAscii Profile Canvas](https://gitascii.com/api/render/igorcbraz)](https://gitascii.com/edit/igorcbraz)

How the Architectural Lifecycles Compare

To see why this improves latency and maintainability, let us compare the request lifecycles of both architectures:

sequenceDiagram
    autonumber
    actor User as Developer Browser
    participant Camo as GitHub Camo Proxy
    participant Stats as Legacy Stats Server
    participant Edge as GitAscii Edge (Next.js Runtime)
    participant DB as GitAscii DB / Cache
    participant GH as GitHub GraphQL API

    rect rgb(240, 240, 240)
        note right of Stats: Legacy Request Cycle (Multiple Cards)
        User->>Camo: Request README Images
        Camo->>Stats: GET /api?username=user&theme=radical&... (Synchronous Engine)
        Stats->>GH: Fetch user statistics (REST/GraphQL)
        GH-->>Stats: Returns raw stats
        Stats-->>Camo: Returns rendered SVG Card
        Camo-->>User: Delivers Card Image
    end

    rect rgb(230, 245, 230)
        note right of Edge: GitAscii Request Cycle (Decoupled Canvas)
        User->>Camo: Request Unified Canvas Image
        Camo->>Edge: GET /api/render/user
        par Fetch Layout Configuration & GitHub Stats
            Edge->>DB: Query JSON design configuration schema
            Edge->>GH: Query user statistics in parallel via GraphQL
        end
        DB-->>Edge: Config schema (layout, styles, ASCII art)
        GH-->>Edge: Raw stats payload
        Edge->>Edge: Assemble responsive unified SVG canvas
        Edge-->>Camo: Returns optimized single SVG (Cache-Control headers)
        Camo-->>User: Delivers responsive unified Canvas
    end

Architecture Comparison Matrix

Feature	Legacy Stats Cards (e.g. github-readme-stats)	GitAscii Unified Canvas
Config Location	Embed in query strings (`?theme=dark&bg_color=...`)	Stored as serialized JSON config in DB
Markdown Overhead	High (bloated URLs, multiple image tags)	Minimal (a single link containing username)
Design Process	Manual text editing of URLs	Interactive, drag-and-drop Visual Builder
Request Overhead	Multiple HTTP calls (waterfall loading)	Single HTTP call (unified responsive SVG)
API Fetching	Synchronous REST / GraphQL per badge	Parallel GraphQL queries executed at Edge
Heavy Processing	Done entirely server-side on request	Offloaded to Client-side (ASCII conversion)

Behind the Scenes: Parallel Edge Fetching

To keep response times under 80ms, GitAscii uses the Vercel Edge Runtime to execute parallel fetching. Instead of waiting sequentially for database configurations and GitHub API responses, we execute them concurrently using Promise.all:

// Example from GitAscii rendering handler on Next.js Edge Runtime
export const runtime = 'edge'

interface RenderRequest {
  username: string
}

export async function GET(request: Request, { params }: { params: RenderRequest }) {
  const { username } = params

  try {
    // 1. Fetch layout configuration and GitHub statistics concurrently
    const [configResponse, githubStats] = await Promise.all([
      fetchLayoutConfiguration(username),
      fetchGitHubGraphQLStats(username),
    ])

    if (!configResponse) {
      return new Response('Profile not found', { status: 404 })
    }

    // 2. Hydrate the pre-processed client-side design layout with live data
    const renderedSvg = assembleUnifiedSvg(configResponse.layout, githubStats)

    // 3. Return the payload with aggressive, safe caching strategies
    return new Response(renderedSvg, {
      status: 200,
      headers: {
        'Content-Type': 'image/svg+xml',
        // Instruct GitHub Camo to cache, but revalidate in the background
        'Cache-Control': 'public, s-maxage=1800, stale-while-revalidate=3600',
        'X-Content-Type-Options': 'nosniff',
      },
    })
  } catch (error) {
    console.error(`Edge rendering failed for ${username}:`, error)
    return new Response('Internal Server Error', { status: 500 })
  }
}

[!TIP]
By using stale-while-revalidate=3600, GitHub's Camo proxy instantly serves the cached version to the reader while triggering a background fetch to update the stats, completely eliminating user-facing latency.

Conclusion

Sticking to traditional stats cards limits your profile to rigid box templates. By decoupling presentation state from HTTP URLs and leveraging Edge servers to assemble unified, adaptive SVGs on the fly, GitAscii provides a modern alternative. It gives you professional, editorial-grade design layouts for your developer portfolio without polluting your Markdown files with query string soup.

Solving Dark/Light Themes in SVGs on GitHub Without DOM Access (Bypassing Camo)

Igor Braz — Tue, 11 Aug 2026 18:57:46 +0000

The most frustrating aspect of GitHub's image proxy, Camo, is not its caching behavior, but the absolute sandboxing of client-side scripts. This constraint creates a classic frontend challenge: how do you deliver a dynamic banner or layout inside a README.md that automatically adjusts to the reader's dark or light theme when you have zero access to the DOM or JavaScript?

Many dynamic profile engines try to solve this by appending theme parameters to the query string (e.g., ?theme=dark). The obvious downside is that this is static: if the reader changes their operating system or browser theme, the image fails to adapt and breaks the layout's aesthetic.

In this deep dive, we look at how GitAscii uses CSS-in-SVG to bypass these constraints, using client-side media queries embedded directly inside vector assets.

The Sandbox Constraints of GitHub Camo

When you embed an image link in a markdown file, GitHub's markdown parser processes it and redirects it through the Camo proxy. In the browser, this image is rendered inside a standard HTML <img> tag:

<img src="https://camo.githubusercontent.com/.../img.svg" alt="Dynamic Canvas" />

According to the W3C specifications for SVG integration, when an SVG file is loaded via an <img> tag (or as a CSS background-image):

JavaScript is fully disabled: Any <script> tags inside the SVG are ignored and blocked by the browser's security sandbox.
External resources are blocked: The browser will not fetch external stylesheets (<link rel="stylesheet">) or external web fonts declared within the SVG.
DOM Isolation: The SVG is rendered in its own separate document context. It cannot query the parent document (the GitHub repository page) or inspect class attributes like .theme-dark on the <html> or <body> elements.

Bypassing the Sandbox with Embedded Media Queries

Although external resources and scripts are blocked, the browser's layout engine still evaluates internal style sheets declared within the SVG itself. Because the SVG is parsed as an XML document, rules written inside <style> blocks are processed in the user's browser context.

This means we can embed the standard CSS media query @media (prefers-color-scheme: dark) inside the SVG payload returned by our Edge server. When the reader's browser renders the SVG, it evaluates the media query against the user's system preferences (dark or light mode) and applies the correct styling.

<svg xmlns="http://www.w3.org/2000/svg" width="800" height="220" viewBox="0 0 800 220">
  <style>
    /* -------------------------------------------------------------
       Default styles (Light Mode configuration)
       ------------------------------------------------------------- */
    .canvas-bg {
      fill: #ffffff;
      stroke: #e1e4e8;
      stroke-width: 1px;
      transition: fill 0.3s ease, stroke 0.3s ease;
    }
    .text-title {
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
      font-weight: 600;
      font-size: 16px;
      fill: #24292e;
    }
    .text-body {
      font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
      font-size: 14px;
      fill: #586069;
    }
    .accent-bar {
      fill: #0366d6; /* GitHub Classic Light Blue */
    }

    /* -------------------------------------------------------------
       Media Query override (Executed by the reader's browser)
       ------------------------------------------------------------- */
    @media (prefers-color-scheme: dark) {
      .canvas-bg {
        fill: #0d1117; /* GitHub Dark canvas background */
        stroke: #30363d;
      }
      .text-title {
        fill: #c9d1d9; /* GitHub Dark text color */
      }
      .text-body {
        fill: #8b949e;
      }
      .accent-bar {
        fill: #c5ff4a; /* GitAscii Lime Accent */
      }
    }
  </style>

  <!-- Vector Layout Markup -->
  <rect class="canvas-bg" width="100%" height="100%" rx="8" />
  <rect class="accent-bar" x="0" y="0" width="8" height="100%" rx="4" />

  <text class="text-title" x="30" y="45">GitAscii Layout Engine</text>
  <text class="text-body" x="30" y="90">> Status: Active</text>
  <text class="text-body" x="30" y="120">> Theme Mode: Auto-Detecting System Colors</text>
  <text class="text-body" x="30" y="150">> Cache Resolution: Edge-Triggered</text>
</svg>

[!NOTE]
Even though the image file is fetched from GitHub's Camo CDN cache, the browser performs CSS rules evaluation locally. This guarantees that if a user switches their OS theme from light to dark, the SVG shifts color schemes instantly, without triggering a network request or requiring a page reload.

Request and Evaluation Architecture

The diagram below details the boundary between server caching and client evaluation:

                  SERVER-SIDE (Edge & CDN)                    │       CLIENT-SIDE (Browser)
                                                              │
┌──────────────┐         ┌─────────────┐       ┌────────────┐ │ ┌────────────────────────────────┐
│ GitAscii DB  ├────────>│ Vercel Edge ├──────>│ GitHub CDN │ │ │ Reader Browser                  │
│ Layout Config│         │ XML Compile │       │ (Camo Cache) │ │ │                                │
└──────────────┘         └─────────────┘       └─────┬──────┘ │ │ 1. Load image: <img src="camo"> │
                                                     │        │ │ 2. Parse XML markup            │
                                                     └───────────> 3. Read internal <style>      │
                                                              │ │ 4. Evaluate system theme       │
                                                              │ │ 5. Render SVG colors dynamically│
                                                              │ └────────────────────────────────┘

Key Considerations for Dynamic Themes

When using CSS-in-SVG for GitHub profiles, keep the following guidelines in mind:

Avoid External Font References: Font files imported via @import url(...) inside the SVG <style> tag will be blocked. Stick to system font stacks (e.g., -apple-system, monospace, or standard fonts like Courier New) to ensure clean rendering.
Set XML Namespace Attributes: Always include xmlns="http://www.w3.org/2000/svg" in your root <svg> tag. Without this, browsers might fail to parse the XML hierarchy, which prevents style sheets from applying.
Use Transition Effects Sparingly: While CSS transition rules (like transition: fill 0.3s ease) work in modern browsers, they can consume CPU cycles if there are too many animated SVG nodes. Focus transitions on background and main text layers.

[!TIP]
If you need to debug SVG styling issues, open the raw SVG file directly in your browser. Inspect it using your developer tools to view the applied CSS classes and toggle dark/light mode emulation.

Conclusion

Open web standards like XML, CSS, and media queries provide robust workarounds for security sandboxes and CDN caching limits. By designing edge-rendered assets that contain their own responsive stylesheets, you can bypass GitHub Camo's strict scripting limitations and deliver theme-aware components that load instantly.

Top 10 Hacks to Make Your GitHub README Actually Interesting in 2026 🔥

Igor Braz — Thu, 06 Aug 2026 20:33:42 +0000

Top 10 Hacks to Make Your GitHub README Actually Interesting in 2026 🔥

A recruiter, hiring manager, or open-source maintainer spends an average of 6 seconds looking at your GitHub profile before deciding whether to explore further. Seeing a wall of default unformatted text is the fastest way to lose their attention.

Your GitHub profile README is the landing page of your engineering career. In this guide, we will look at 10 advanced hacks to turn your profile from a static resume into an interactive, high-performance portfolio.

Static vs. Dynamic README Elements

Before jumping into the list, let's understand the tradeoff between static layouts and dynamic widgets:

Feature Type	Implementation Method	Caching Impact	Best Use Case
Static Markdown	Direct README.md text	None (cached indefinitely)	Biography, contact info, core skill lists
Dynamic SVGs	Hosted Serverless APIs	Heavy (Camo cache controls apply)	Real-time coding hours, Spotify status, live stats
Action-Generated	GitHub Actions scheduled writes	Rebuilds on push	Blog feeds, daily statistics, interactive games

1. Leverage Dynamic Typing SVGs

Adding an animated typing banner is the easiest way to give your profile a modern terminal aesthetic. Using readme-typing-svg, you can list your specialties or key projects.

[![Typing SVG](https://readme-typing-svg.demolab.com?font=Fira+Code&weight=600&size=22&pause=1000&color=F85B44&width=435&lines=Senior+Backend+Engineer;System+Architect;Open+Source+Maintainer)](https://git.io/typing-svg)

[!TIP]
Use standard web-safe fonts or specify system monospaced choices like Fira Code or JetBrains Mono to prevent layout shifts when the SVG renders inside the browser.

2. Ditch Standard Markdown Tables for GitAscii

Stop writing complex nested HTML tables to align your stack icons. It creates bloated, unreadable Markdown code and frequently breaks on mobile viewports. Instead, use GitAscii, a visual workspace built for GitHub profiles.

GitAscii lets you arrange terminal-style layout widgets, GitHub statistics, and custom ASCII art in a visual editor. The tool compiles your design into a single SVG URL.

[![My GitAscii Profile](https://gitascii.com/api/render/yourusername)](https://gitascii.com/edit/yourusername)

Why it is superior:

Zero Client-Side Overhead: The visitor only downloads a single highly-optimized SVG.
Pixel-Perfect Grids: Eliminates Markdown styling limits.
Auto-updating: The backend updates statistics automatically when requested by the GitHub proxy.

3. Embed WakaTime Coding Metrics

Instead of showing only commit counts (which can be easily inflated), show the language metrics and time you spend actively typing inside your IDE.

![WakaTime Stats](https://github-readme-stats.vercel.app/api/wakatime?username=yourusername&layout=compact&langs_count=8&theme=radical)

[!WARNING]
WakaTime lists your active editing time. Ensure you review WakaTime's privacy dashboard settings to prevent leaking internal project names or proprietary repositories.

4. Interactive Chess Games and Mini-Games

You can run an active chess game right on your profile. The board is rendered as a dynamic SVG, and users play against each other by clicking a move link.

  A   B   C   D   E   F   G   H
8 [♜][♞][♝][♛][♚][♝][♞][♜] 8
7 [♟][♟][♟][♟][ ][♟][♟][♟] 7
6 [ ][ ][ ][ ][ ][ ][ ][ ] 6
5 [ ][ ][ ][ ][♟][ ][ ][ ] 5
4 [ ][ ][ ][ ][ ][ ][ ][ ] 4
3 [ ][ ][ ][ ][ ][ ][ ][ ] 3
2 [♙][♙][♙][♙][♙][♙][♙][♙] 2
1 [♖][♘][♗][♕][♔][♗][♘][♖] 1
  A   B   C   D   E   F   G   H

When a user clicks a move, it directs them to open a pre-filled GitHub Issue in your repository. A GitHub Action workflow triggered by the issues event parses the move, updates the game state file, and commits the change, triggering the SVG board update.

5. Automated Blog Post Feeds

If you write articles on Dev.to, Medium, or Hashnode, do not update your profile links manually. Setup a scheduled GitHub Action to pull the RSS feed and inject the list into your README.

Create the following workflow file in your profile repository:

# .github/workflows/blog-posts.yml
name: Update Blog Posts

on:
  schedule:
    # Runs every 6 hours
    - cron: '0 */6 * * *'
  workflow_dispatch: # Allows manual trigger

jobs:
  update-readme:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v3

      - name: Fetch and Inject Blog Posts
        uses: gautamkrishnar/blog-post-workflow@master
        with:
          feed_list: 'https://dev.to/feed/yourusername'
          max_post_count: 5

Inside your README.md, place these comment tags where you want the feed to appear:

<!-- BLOG-POST-LIST:START -->
<!-- BLOG-POST-LIST:END -->

6. Use HTML Details Tags for Accordions

Keep your profile clean by moving secondary details—like certifications, system config configurations, or dotfiles—into collapsible panels.

<details>
  <summary>🛠️ View My Terminal & Hardware Setup</summary>

### Development Environment

- **OS**: macOS Sequoia / Arch Linux
- **Terminal**: Alacritty + Tmux
- **Editor**: Neovim (configured using Lua)
- **Shell**: Zsh with Starship prompt

</details>

7. Dynamically Updated Spotify Widget

Show recruiters your coding soundtrack by embedding a Spotify widget. By setting up a serverless function that integrates with the Spotify Web API, you can generate an SVG showing your active playback state.

[![Spotify Status](https://novatfy.vercel.app/api/spotify?username=yourusername)](https://open.spotify.com/user/yourusername)

The serverless function handles the OAuth refresh token flow in the background, retrieves the track metadata and album art, converts the image to base64, and renders the dynamic progress bar as an SVG wrapper.

8. Add GitHub Profile Trophy Cards

Add gamified trophies to your profile based on your open-source accomplishments. It displays awards for stars, total commits, pull request merges, and account age.

[![GitHub Trophies](https://github-profile-trophy.vercel.app/?username=yourusername&theme=onedark)](https://github.com/ryo-ma/github-profile-trophy)

[!NOTE]
The trophies are grouped by tiers: C (bronze), B (silver), A (gold), and S (secret/platinum) based on your contribution statistics.

9. Adapt SVG Assets to Light and Dark Modes

To prevent custom architecture diagrams or flowcharts from being unreadable in dark mode, embed media queries inside your SVG source code:

@media (prefers-color-scheme: dark) {
  .canvas-bg {
    fill: #0d1117;
  }
  .text-title {
    fill: #ffffff;
  }
  .grid-lines {
    stroke: #30363d;
  }
}
@media (prefers-color-scheme: light) {
  .canvas-bg {
    fill: #ffffff;
  }
  .text-title {
    fill: #24292f;
  }
  .grid-lines {
    stroke: #d0d7de;
  }
}

This ensures that the image matches the reader's operating system or GitHub interface theme without needing duplicate files.

10. Center Your Assets with HTML Divs

Markdown aligns elements to the left by default. To make your profile look balanced across wide monitors and mobile viewports, wrap your header badges and main statistics in centered HTML div blocks.

<div align="center">
  <img src="https://readme-typing-svg.demolab.com?font=Fira+Code&lines=Hello+World" alt="Header" />

  <p>
    <a href="https://linkedin.com/in/yourprofile">
      <img
        src="https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin"
        alt="LinkedIn"
      />
    </a>
  </p>
</div>

Conclusion

A well-crafted profile README shows your attention to detail and engineering quality. By combining dynamic assets (like GitAscii or automated blog workflows) with responsive design guidelines, you can build a portfolio that stands out.

GitAscii: A Visual Editor for GitHub Profile READMEs

Igor Braz — Sat, 01 Aug 2026 03:42:11 +0000

GitAscii: A Visual Editor for GitHub Profile READMEs

Your GitHub profile is your digital business card in the open-source community. However, maintaining a profile README that is visually striking, informative, and dynamically updated often turns into a tedious chore. Developers are forced to choose between manually editing Markdown files, relying on multiple mismatched third-party statistics generators, or dealing with broken alignments on mobile devices.

GitAscii solves this problem by introducing a unified, visual drag-and-drop workspace. Instead of writing nested HTML tables or configuring multiple external repositories, you construct your profile visually. The editor generates a configuration schema, which is compiled on-demand into a single, highly optimized, theme-responsive SVG.

The Core Problem: Why Profile READMEs Are Fragile

Building a custom profile README presents several technical challenges:

GitHub Camo Proxying: GitHub routes all README images through camo.githubusercontent.com to prevent mixed-content warnings and trace user IP addresses. This proxy caches images aggressively, meaning any dynamic stats must declare strict caching policies or risk serving stale data.
Responsive Alignment: Markdown doesn't natively support grid layouts or advanced flexbox styling. Creating a multi-column layout with status badges, coding stats, and bio sections requires writing raw HTML <table> or <div> structures that frequently break on narrow screens.
Theme Synchronization: GitHub supports light and dark themes. Most external badge generators return flat images with hardcoded background colors, rendering them illegible when a user toggles their GitHub interface theme.
Maintenance Overhead: Keeping metrics up-to-date (like recent blog posts, current repository stars, or Spotify listening state) requires background cron jobs or GitHub Actions that push commits to your profile repository, cluttering your Git history.

The GitAscii Architecture

GitAscii combines a browser-based layout engine with an Edge-hosted rendering pipeline to bypass these limitations.

graph TD
    A[Visual Builder React UI] -->|Saves Configuration| B[(Database / URL State)]
    C[GitHub Camo Proxy] -->|Requests SVG /api/render/:user| D[Next.js Edge Route]
    D -->|Fetches Config & GitHub API| E[Data Aggregator]
    E -->|Renders Tailwind-like HTML| F[Satori Engine]
    F -->|Outputs Dynamic SVG| C
    C -->|Renders to| G[Client Browser]

1. The Visual Editor (Client-Side)

Built using Next.js, React, and Tailwind CSS, the editor enables you to arrange layout elements (widgets) on a grid canvas. The layout is stored as a JSON schema, defining positions, dimensions, widget types, and user configuration.

2. Edge Rendering & Caching Pipeline

Instead of rendering HTML to client-side browsers and making users download hundreds of kilobytes of JavaScript, GitAscii serves a single <img src="..."> URL. When GitHub Camo requests this URL, our serverless Edge handler fetches the user's layout schema, aggregates live statistics from the GitHub API, and compiles the components using Satori. Satori converts HTML/CSS elements styled with Tailwind inline-styles into standard, clean SVG paths.

3. Dynamic Caching & Bypassing Camo Latency

To balance fast load times and fresh stats, GitAscii uses a tailored cache invalidation strategy. We leverage the Cache-Control header to control how the GitHub Camo proxy and the user's browser handle the asset.

Cache-Control: public, max-age=0, s-maxage=300, stale-while-revalidate=600

max-age=0: Instructs the user's browser not to cache the image, ensuring that returning to the page triggers a re-fetch.
s-maxage=300: Tells GitHub Camo to cache the SVG for exactly 5 minutes (300 seconds).
stale-while-revalidate=600: Allows Camo to serve the stale cached SVG immediately while fetching the fresh version in the background, minimizing TTFB (Time to First Byte) latency for the visitor.

Technical Deep Dive: Browser-Side ASCII Art Conversion

One of GitAscii’s unique widgets is the client-side ASCII art converter. Users can upload an image, and GitAscii converts it into a terminal-style monochrome or colored text representation.

To achieve this without server-side processing overhead, we perform canvas manipulation directly in the browser using the following JavaScript logic:

/**
 * Converts a source image file into an ASCII string based on pixel luminance.
 *
 * @param imageEl - The loaded HTMLImageElement.
 * @param cols - Number of columns in the target ASCII art (controls horizontal resolution).
 * @param rows - Number of rows in the target ASCII art (controls vertical resolution).
 * @returns The converted ASCII text.
 */
export function convertImageToAscii(imageEl: HTMLImageElement, cols: number, rows: number): string {
  const canvas = document.createElement('canvas')
  const ctx = canvas.getContext('2d')
  if (!ctx) return ''

  // Set visual dimensions to match target resolution
  canvas.width = cols
  canvas.height = rows

  // Draw image scaled down to columns * rows
  ctx.drawImage(imageEl, 0, 0, cols, rows)

  // Retrieve raw RGBA pixel data
  const imgData = ctx.getImageData(0, 0, cols, rows)
  const data = imgData.data

  // ASCII character ramp ordered from densest (darkest) to sparsest (lightest)
  const charRamp = '@#S%?*+;:+,. '
  const rampLength = charRamp.length
  let asciiResult = ''

  for (let y = 0; y < rows; y++) {
    for (let x = 0; x < cols; x++) {
      const idx = (y * cols + x) * 4
      const r = data[idx]
      const g = data[idx + 1]
      const b = data[idx + 2]
      const a = data[idx + 3]

      // If pixel is fully transparent, treat it as whitespace
      if (a < 10) {
        asciiResult += ' '
        continue
      }

      // Calculate relative luminance using standard Rec. 709 weights
      const luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b

      // Map luminance (0-255) to a character index in the ramp
      const charIndex = Math.floor((luminance / 255) * (rampLength - 1))
      asciiResult += charRamp[charIndex]
    }
    // Append newline at the end of each row
    asciiResult += '\n'
  }

  return asciiResult
}

[!NOTE]
Since standard text characters are taller than they are wide, we recommend correcting the aspect ratio by reducing the vertical row count (rows) relative to cols by a factor of roughly 0.55 before rendering to prevent the ASCII art from stretching vertically.

Achieving Theme Responsiveness in Generated SVGs

To adapt to GitHub's light and dark themes seamlessly, GitAscii inserts a dynamic CSS stylesheet block inside the generated SVG file. By utilizing the standard system media queries within the SVG definition itself, we target GitHub's system theme variables:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 400" width="100%" height="100%">
  <style>
    /* Default dark theme values */
    .bg { fill: #0d1117; }
    .text-primary { fill: #c9d1d9; font-family: 'Fira Code', monospace; }
    .text-accent { fill: #58a6ff; font-weight: bold; }

    /* Override rules when light mode is preferred */
    @media (prefers-color-scheme: light) {
      .bg { fill: #ffffff; }
      .text-primary { fill: #24292f; }
      .text-accent { fill: #0969da; }
    }
  </style>

  <!-- Background Layer -->
  <rect class="bg" width="100%" height="100%" rx="8" />

  <!-- Dynamic Content -->
  <text x="40" y="60" class="text-accent" font-size="24">GitAscii Dashboard</text>
  <text x="40" y="100" class="text-primary" font-size="16">> Initializing widgets...</text>
</svg>

When GitHub’s container renders this inline or via an <img> tag, the user’s client browser processes the @media query and instantly shifts colors without requesting a new asset from the server.

Join the Project

GitAscii is completely open-source and built for developers who want absolute control over their profiles without writing thousands of lines of boilerplate Markdown.

[!TIP]
You can host GitAscii yourself! The application is packaged to run within Vercel Serverless Functions, Netlify, or standard Docker containers. Check out our repository instructions on self-hosting config variables to spin up a private instance with custom GitHub OAuth scopes.

Repository: https://github.com/Igorcbraz/GitAscii
Visual Editor: https://gitascii.com