I Built a GitHub Profile README — the 'It Won't Show Up' Traps and Tips to Stand Out

🌐 This is the English version of an article I originally wrote in Japanese on Zenn. The original is linked as the canonical source.

Introduction

I usually write "I built a small CLI tool in TypeScript / Python" style posts. This time it's a bit different: a write-up about building my GitHub profile README.

I'm an engineer who spent 15+ years mostly on legacy Java, and I'm now learning TypeScript and Python on my own, publishing what I learn on Zenn and dev.to. Once I had a decent number of learning projects piling up, I decided it was time to build "the face of my GitHub."

Here's the conclusion up front:

• Writing the README itself is not hard. You just line up Markdown and badges.
• But I kept getting stuck on "it doesn't show up on my profile."
• And there was a second trap: the GitHub Stats badge was broken and wouldn't render.

This post focuses on the points that are surprisingly easy to miss if you only read the official docs, using my own profile as a concrete example.

Here's the finished result 👉 github.com/uya0526-design

💡 I'm writing this for people building a profile README for the first time. If you've written repository READMEs before but never the profile one, this should be about the right level.

What is a profile README, anyway?

GitHub has two kinds of README, and it's easy to confuse them at first. Let me separate them clearly.

Type	Where it lives	Where it shows up	Role
Repository README	README.md inside each repo	Top of that repository	Explaining the project and how to use it
Profile README	README.md inside a repo named exactly like your username	Top of your profile page (github.com/username)	Self-introduction and the "face" of your portfolio

The key point: the profile README differs from the repository README you normally write, both in where it lives and what it's for.

The essentials of making one

The mechanism is simple. You create a repository whose name exactly matches your username, and put a README.md at its root.

• Username uya0526-design → repository uya0526-design/uya0526-design
• GitHub treats this repo as a "special repository"
• Put README.md at the root
• Make the repository Public

In theory it should now show up... and this is where I fell into the swamp.

Trap 1: the README doesn't show up

I wrote the README, pushed it, and nothing appeared on my profile. I burned a fair amount of time in this state. Let me share the final cause and a checklist for narrowing it down.

The real cause: I hadn't pressed the "Share to profile" button

This was the actual culprit in my case.

• Just creating the special repository does not always auto-publish it to your profile
• There's a "Share to profile" button on the repository page, and only after pressing it does the README appear on your profile
• The button is subtle, and I completely missed it

✅ Takeaway: When your README won't show up even after you wrote and pushed it, first look for the "Share to profile" button on the repository page. In my case, this one action got me out of the swamp.

Checklist for when it won't show up

That said, this isn't the only possible cause. There are several easy-to-miss points. Checking them top to bottom is efficient.

1. Does the repository name match your username exactly?
   • Watch out for mixing up hyphen - and underscore _
   • Match case as well
2. Is the repository Public? (Private repos won't show up)
3. Is README.md at the root? (It won't be picked up from a subfolder)
4. Does the README have content? (An empty file won't show)
5. Is the README at the root of the default branch?
   • The profile README only references the README on the "default branch"
   • If you created it locally on master, pushed, and added main afterward, the default branch and the branch holding the README can end up out of sync
   • Check under Settings → General → Default branch
6. Did you press "Share to profile"? ← my actual cause
7. Propagation delay / cache
   • There can be a lag right after pushing. Wait a bit, or hard reload (Ctrl + Shift + R)

Number 5 is an especially easy trap for people who used master by local habit. Maybe a classic "ex-SE" mistake.

A tip for checking: view it while logged out

This one helped in a quiet but real way.

• Open github.com/username in incognito / InPrivate mode
• When you're logged in, the editing UI takes priority and the appearance can differ, so checking "how others see it" while logged out is the reliable way
• When it's correctly reflected, the README appears large, above your Pinned repositories
  • In other words, if Pinned is at the very top, the README hasn't been reflected yet

Trap 2: the GitHub Stats badge is broken

You know that "GitHub Stats" card (github-readme-stats) you often see on profile READMEs? When I pasted it in, the image turned into a broken-image icon.

The cause: the official instance was paused

When I opened the image URL directly in a browser, it returned 503 SERVICE_UNAVAILABLE / DEPLOYMENT_PAUSED.

• This means the official deployment (on a free Vercel tier) is temporarily paused due to congestion or limits
• Since it's a service shared by many users, this is a known issue that happens intermittently
• It's not a problem on your side

In other words, my README was fine — the shared service I was riding on happened to be down.

The fix: self-host on your own Vercel

If it's a temporary outage you can just wait, but I wasn't comfortable putting something that might go down again on the "face" of my profile. So I decided to self-host on my own Vercel account. That removes the dependency on someone else's quota.

Here are just the key steps (the official repository README has the details).

1. Create a Vercel account (the free Hobby plan is enough for personal use)
2. Fork github-readme-stats to your own account
3. Get a GitHub Personal Access Token (classic, with the public_repo scope)
4. Import it into Vercel, set the token as the environment variable PAT_1, and Deploy
5. Note the fixed Domains URL that gets issued (not the temporary URL that changes per deploy)
6. Replace the image URL in your README, swapping the official instance for your own Domains URL

After swapping, the embed looks like this (replace the URL part with your own):

![GitHub Stats](https://[your Domains URL]/api?username=[username]&show_icons=true&hide_border=true&count_private=true)
![Top Languages](https://[your Domains URL]/api/top-langs/?username=[username]&layout=compact&hide_border=true)

⚠️ Security note: A Personal Access Token is shown only once — copy it before you close the screen. Never write the token directly in your code or README; pass it only as a Vercel environment variable, and don't leak it.

If you get stuck signing up for Vercel (phone verification error): When signing up via GitHub, phone verification can fail with "The user could not be found" (this seems to be a known Vercel issue). If that happens, use the form at Vercel Account Recovery to explain the situation and contact support.

You can see my self-hosted card working in the "GitHub Stats" section near the bottom of my profile.

📝 This self-hosting procedure turned out to be enough material for its own article. I plan to split out the detailed steps (with screenshots) into a separate post.

💡 Lesson: Assume that badges depending on external services will go down someday. Self-host the important ones, or place them where it isn't fatal if they break.

What to highlight: from a reskilling ex-engineer's view

Beyond just "making a working README," the real question is what you communicate to the reader (recruiters, collaborators, peers). My position is "15+ years of real experience, but modern tech is still ahead of me," so I focused on showing that honestly and attractively.

What I included

In my actual profile, I structured it roughly in this order:

• Header (one-line catch + badges): years of experience, key certifications, and what I'm learning, at a glance
• About Me: which domains I've worked in and for how long, plus where I am now (reskilling)
• How I Learn: less abstract self-PR, more "how I actually move my hands"
• Certifications: a table with dates (high credibility, easy to read)
• Tech Stack: badges split into "professional experience" and "currently learning"
• Featured Projects: link + tech used + what I practiced, as a set
• Writing: links to Zenn / dev.to
• GitHub Stats: the self-hosted version above

Ways of thinking that work for self-promotion

Four things I paid special attention to:

1. Concrete > abstract. "Lots of Java experience" is weaker than "15 years of enterprise Java in telecom, logistics, and finance." Specific industry names add credibility.
2. Separate real experience from what you're learning, honestly. Categorizing accurately without exaggeration actually builds trust. That's why I split my Tech Stack into "Professional experience" and "Currently learning & building."
3. Show how you learn. In my case I wrote about the process itself: "I don't let AI write my code — I implement first, then have AI review," "I design my own tests," "I don't take AI's suggestions at face value — I verify them with actual commands." Showing the process is itself a statement about your attitude as an engineer.
4. Stack up "finished and published" wins, however small. A pile of small projects with tests, a README, and a learning log is plain but strong.

A small trick for going bilingual

Assuming some global readers, I wrote mainly in English while folding a Japanese version into a collapsible block. That keeps an English-first layout while still being readable for Japanese speakers.

<details>
<summary>Japanese profile (click to expand)</summary>

(Japanese body goes here)

</details>

📝 GitHub READMEs support some HTML (like collapsible blocks and centered text), but behavior can vary by environment. Always check the actual rendering after publishing.

Wrap-up: a checklist for next time

Finally, a checklist for my future self (and for you, if you read this far).

• [ ] Created a repository with the same name as your username (exact match)
• [ ] Made it Public
• [ ] Put README.md at the root of the default branch
• [ ] Pressed the "Share to profile" button
• [ ] Opened github.com/username in incognito mode to verify
• [ ] Checked that external badges (Stats, etc.) render (self-host if not)
• [ ] Wrote "real experience" and "currently learning" separately and accurately
• [ ] Made the content convey your learning process and consistency

A profile README isn't something you make once and forget — it's a place to keep showing your growth. I'll keep updating Featured Projects and "Next up" as projects accumulate.

Here's the finished profile 👉 github.com/uya0526-design

Thanks for reading. I hope it helps anyone else stuck in the "it won't show up" swamp.