<GitBlend/>
Knowledge Base|
GitHub ProfileBeginner8 min read

How to Add a Contribution Graph to Your GitHub README

Learn how to embed dynamic contribution graphs in your GitHub profile README. Step-by-step guide with GitBlend integration.

Last updated:

Why Contribution Graphs Matter

Your GitHub contribution graph is one of the most powerful visual elements on your developer profile. Unlike badges that list skills or text that describes experience, a contribution graph provides objective, verifiable proof of your coding activity over time. It tells a story that words simply cannot.

When someone visits your GitHub profile, the contribution graph immediately answers several questions: Does this person actively code? Are they consistent? Do they have a sustained track record, or are there long gaps? This information shapes first impressions faster than any written content.

The Psychology of Visual Proof

Humans process visual information 60,000 times faster than text. A dense contribution graph communicates "active developer" in a fraction of a second. This matters because:

  • •Recruiters spend seconds on profiles: Studies show hiring managers spend an average of 6-7 seconds on initial profile scans. A strong visual signal like a contribution graph can make the difference between deeper investigation and moving on.
  • •Visual patterns build trust: A year of consistent contributions creates a pattern that signals reliability. It suggests someone who shows up regularly, not just in bursts of motivation.
  • •Numbers are persuasive: Seeing "1,247 contributions in the last year" in visual form is more impactful than reading the same statistic in text.

The Problem with Native Graphs

GitHub's built-in contribution graph appears on your profile page, but it has limitations:

  • •It's not in your README: The README appears first, above the contribution graph. Many visitors never scroll down to see the native graph.
  • •No customization: You're stuck with GitHub's green color scheme, regardless of your profile's aesthetic.
  • •Single platform: If you work on GitLab or other platforms, that activity is invisible.
  • •No embedding: You can't place the native graph in documentation, portfolios, or other websites.
GitBlend solves these problems by providing embeddable, customizable contribution graphs that work anywhere markdown is supported.

Prerequisites: Setting Up Your Profile README

Before adding a contribution graph, you need a GitHub profile README. This is a special repository that displays content directly on your profile page.

Creating the Profile Repository

GitHub treats a repository with your exact username as a special profile repository. Here's how to create it:

  • Navigate to repository creation: Go to github.com/new while logged in.">
  • Enter your exact username: In the "Repository name" field, type your GitHub username exactly as it appears. This is case-sensitive. If your username is "JohnDoe", the repository must be named "JohnDoe".">
  • Watch for the confirmation: GitHub will display a message: "You found a secret! [username]/[username] is a special repository that you can use to add a README.md to your GitHub profile."">
  • Set visibility to Public: The repository must be public for your README to display on your profile.">
  • Initialize with a README: Check "Add a README file" to create the initial file.">
  • Create the repository: Click "Create repository" to finish.">

    • Your README.md file in this repository will now appear at the top of your GitHub profile, above your pinned repositories.

    Understanding README Positioning

    When visitors land on your profile, they see:

    1. 1Your profile picture and bio
    2. 2Your README content (from the special repository)
    3. 3Your contribution graph
    4. 4Your pinned repositories
    Since the README appears first, it's the ideal place for your contribution graph. Visitors will see it immediately without needing to scroll.

    Adding Your Contribution Graph

    The Basic Embed

    GitBlend generates contribution graphs as SVG images that you embed using standard markdown image syntax:

    Markdown 
    ![GitHub Contributions](https://gitblend.com/api/contributions/github?username=sergebulaev)

    Replace "sergebulaev" with your own GitHub username. When GitHub renders your README, it fetches this image from GitBlend and displays your contribution graph.

    Understanding the URL Structure

    The GitBlend URL follows a predictable pattern:

    `` https://gitblend.com/api/contributions/[platform]?username=[your-username]&[options] `

    Platform options:
    • •github - Shows only GitHub contributions
    • •combined - Shows GitHub and GitLab contributions merged (requires authentication)
    Common parameters:
    • •username - Your platform username
    • •theme - Visual theme name
    • •bg - Custom background color (hex code without #)

    Platform-Specific Graphs

    GitHub contributions only:

    Markdown 
    ![GitHub Contributions](https://gitblend.com/api/contributions/github?username=sergebulaev)

    This displays your GitHub contribution history in the default theme.

    GitLab contributions only:

    For GitLab, sign in to GitBlend and use your personalized URL from the dashboard.

    Combined GitHub and GitLab:

    Markdown 
    ![All Contributions](https://gitblend.com/api/contributions/combined?github=yourgithub&gitlab=yourgitlab&token=yourtoken)

    The combined view requires authentication. Sign in at gitblend.com to get your personalized URL with the correct token.

    Theme Customization

    GitBlend offers over 20 themes to match any profile aesthetic. Each theme defines colors for the background, grid, and contribution intensity levels.

    Available Themes

    Classic Themes
    • •github - GitHub's signature green gradient
    • •gitlab - GitLab's purple contribution colors
    • •light - Clean white background with subtle colors
    • •dark - Dark background for dark mode profiles
    Popular Dark Themes
    • •dracula - Purple and pink on dark background
    • •nord - Arctic blue tones
    • •tokyo - Tokyo Night color palette
    • •monokai - Classic editor theme
    • •synthwave - Retro 80s neon colors
    Nature Themes
    • •ocean - Deep blue oceanic colors
    • •sunset - Warm orange and red tones
    • •forest - Green woodland palette
    • •aurora - Northern lights inspired
    • •rose - Pink gradient
    Additional Options
    • •cyberpunk - High-contrast neon
    • •coral - Vibrant coral tones
    • •solarized - Popular terminal theme
    • •mint - Fresh green palette
    • •autumn - Fall color scheme
    • •lavender` - Soft purple tones

    Applying a Theme

    Add the theme parameter to your URL:

    Markdown 
    ![Contributions](https://gitblend.com/api/contributions/github?username=sergebulaev&theme=dracula)

    Custom Background Colors

    Override the theme's background with a hex color code:

    Markdown 
    ![Contributions](https://gitblend.com/api/contributions/github?username=sergebulaev&theme=dark&bg=0d1117)

    The color code should be without the # symbol. The example above uses GitHub's dark mode background color.

    Layout and Styling

    Centering Your Graph

    For a polished look, center your contribution graph:

    Markdown 
    <div align="center">

![GitHub Contributions](https://gitblend.com/api/contributions/github?username=sergebulaev&theme=github)

</div>

    The blank lines before and after the image are important for proper markdown rendering.

    Adding Context

    Don't just drop in a graph. Give visitors context:

    Markdown 
    ## My Coding Activity

I believe in consistent progress over time. Here's my contribution history:

![GitHub Contributions](https://gitblend.com/api/contributions/github?username=sergebulaev&theme=nord)

Most of my recent work focuses on TypeScript and React applications.

    Combining with Other Elements

    Contribution graphs work well alongside other profile elements. Consider this layout:

    Markdown 
    ## About Me

A brief introduction here.

## My Activity

![GitHub Contributions](https://gitblend.com/api/contributions/github?username=sergebulaev&theme=github)

## Tech Stack

Your technology badges here.

    Dark Mode Compatibility

    GitHub supports both light and dark themes. Your contribution graph should look good in both modes.

    Using the Picture Element

    The HTML picture element lets you serve different images based on the user's color scheme preference:

    HTML 
    <picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://gitblend.com/api/contributions/github?username=sergebulaev&theme=dark">
  <source media="(prefers-color-scheme: light)" srcset="https://gitblend.com/api/contributions/github?username=sergebulaev&theme=light">
  <img alt="GitHub Contributions" src="https://gitblend.com/api/contributions/github?username=sergebulaev&theme=github">
</picture>

    This serves a dark-themed graph to dark mode users and a light-themed graph to light mode users. The fallback image (in the img tag) is used if media queries aren't supported.

    ! Warning
    Don't use JavaScript for theme switching. GitHub READMEs don't execute JavaScript for security reasons. Always use the picture element or CSS media queries.

    Best Practices

    Placement Strategies

    Hero position: Place the graph prominently near the top of your README, right after your introduction. This ensures maximum visibility. Activity section: Create a dedicated "My Activity" or "Coding Activity" section with the graph as the centerpiece. Sidebar layout: If using HTML tables for layout, you can place the graph in a sidebar column alongside other profile elements.

    Visual Consistency

    Match your aesthetic: Choose a theme that complements your other profile elements. If you're using Dracula-themed badges, use the Dracula contribution theme. Avoid clutter: One contribution graph is enough. Don't add multiple graphs showing the same data in different themes. Consider contrast: Ensure your graph is readable against your README's background. Dark themes work best on dark-mode-optimized profiles.

    Content Context

    Add narrative: A graph alone is just data. Add a sentence or two explaining your coding focus or patterns. Be authentic: Don't apologize for gaps. Everyone has periods of reduced activity. The overall pattern matters more than individual days.

    Troubleshooting Common Issues

    Graph Not Displaying

    Check the URL: Ensure you're using HTTPS and that the username is spelled correctly (case-sensitive). Verify your profile is public: GitBlend can only access public contribution data. Check your GitHub privacy settings. Wait for caching: Newly created graphs may take a few minutes to appear. Try a hard refresh (Ctrl+Shift+R or Cmd+Shift+R). Check markdown syntax: Ensure you have proper spacing around the image syntax. Missing blank lines can cause rendering issues.

    Incorrect Data

    Caching delay: Contribution data is cached for a few hours. Very recent contributions won't appear immediately. Private contributions: If you've enabled "Private contributions" in your GitHub settings, those will appear as green squares but may be delayed in GitBlend. Time zone differences: Contributions are recorded in UTC. A commit made late at night might appear on the next day in your local time.

    Styling Issues

    Graph too wide: If the graph overflows on mobile, wrap it in a centered div with max-width styling. Wrong colors: Clear your browser cache if you've recently changed themes. The old image may be cached. Alt text not showing: GitHub requires alt text for accessibility. Always include descriptive alt text in your image syntax.

    Advanced Configuration

    Combining Multiple Data Sources

    If you contribute to both GitHub and GitLab, use GitBlend's combined view to show all your activity:

    Markdown 
    ![All My Contributions](https://gitblend.com/api/contributions/combined?github=myuser&gitlab=myuser&token=mytoken&theme=nord)

    This merges contribution counts from both platforms into a single unified graph.

    Embedding in Other Contexts

    GitBlend graphs aren't limited to GitHub READMEs. You can embed them in:

    • •Personal portfolio websites
    • •Project documentation
    • •Blog posts
    • •LinkedIn (as images)
    • •Resumes (printed or digital)
    The same URL works anywhere that displays images.

    Next Steps

    Now that you've added a contribution graph to your README, consider these related guides:

    Ready to enhance your profile?

    Create beautiful contribution graphs for your GitHub profile in seconds with GitBlend.

    Get Started Free

    Related Articles

    How to Create an Awesome GitHub Profile README

    Create a standout GitHub profile with badges, stats, and contribution graphs that impress recruiters.

    Beginner

    GitHub README Badges: Complete Guide for Developers

    Add professional badges to your GitHub README using Shields.io and GitBlend contribution graphs.

    Beginner
    Back to Knowledge Base