Previously the only way you could customise your Github profile was by updating the picture or changing your name. This meant every Github profile looked the same, the options to customise it or to stand out was minimal.

Since then, you have the option to create a custom section using Markdown. You can include your CV, your interests and hobbies to make your profile reflect who you are. It’s one of the main sections that anyone sees when they land on your profile.

In this article I’ll show you how I created my Github readme with a twist. I’ll be using Markdown and solving it’s main problem. The problem that it can be highly restrictive, as you can’t change colours, adjusting positions and spacing can be difficult. To solve there is a way you can add CSS to your Github readme and even add transitions to present a better UX.

But let’s start with creating the readme first. For this, you’ll need to create a new public repository that is exactly what your Github username is. You’ll see a small text showcasing that this will be a unique repository.

Now whatever you update in your [README.md]() file, it will be displayed on your profile. You can use Markdown syntax or HTML to display your content. If you add any inline styling, CSS files or JavaScript, it’ll be stripped by Github, so that solution is a no-go.

The solution

In your README.md file you can include images. That includes SVG files. The loophole that enables us to add CSS is embedding custom HTML and CSS using the foreignObject element in an SVG file. The foreignObject element allows you to include elements from other markup languages inside an SVG graphic.

Let’s create a new file in our repository, called header.svg. In my case, I’d like a text being displayed on my profile saying CodeFlow., with a nice gradient and a typewriter effect. To achieve that, I wrote some CSS and some HTML nested in a foreignObject in my SVG file:

Now let’s update the README.md file to use this SVG as an image and display it in our profile:

And that’s it. It’s really just some CSS and HTML wrapped inside an SVG. Check out the end result below or if you’d like to see in in action, my Github profile is here.