GitHub Markdown Tricks: 8 Hacks I Actually Use in My READMEs

Look, we've all seen those massive wall-of-text READMEs. You land on a repository, scroll for ten seconds, and give up because everything looks like a legal document. When I first set up my public profile, I made this mistake myself. I dumped everything I knew into a single file and hoped people would read it. I listed every framework I'd ever touched, pasted giant configuration logs, and didn't bother formatting any of it.

They didn't. In fact, most people who visited my repos probably bounced within five seconds.

Then I started noticing how top developers structured their pages. They weren't just using bold text and bullet points. They were treating their GitHub README like an actual web page. They used columns, collapsible menus, and embedded media to guide the reader's eye.

Here's the thing: GitHub Flavored Markdown (GFM) has a bunch of hidden features. It actually supports raw HTML, but it's incredibly picky about what it allows. It strips out inline styles, blocks scripts, and ignores plenty of layout tags. So after hours of trial and error (and breaking my profile more times than I'd like to admit), I've put together the formatting tricks I use in almost every repo. No fluff, just the stuff that actually works.

1.The Collapsible Section Trick

This is honestly my favorite trick. If you have a massive block of text — like installation logs, a detailed API response, or a giant list of minor projects — don't force everyone to scroll past it.

You can hide it behind a clean, clickable toggle using HTML details tags. I do this constantly for troubleshooting steps.

<details>
  <summary>Click here to see the full API response</summary>

  ```json
  {
    "status": "success",
    "data": "Wow, this didn't ruin the page layout!"
  }
  ```
</details>

Notice the blank line after the summary tag? That's not a typo. If you skip that blank line, GitHub won't render the markdown inside the block properly. I learned that the hard way after fighting with my layout for half an hour.

2.Using HTML Tables for Actual Layout

Standard markdown tables are fine for data, but they suck for layout. What if you want to put two lists side by side? Or place an image next to some text? You can't do that with basic markdown.

Instead, use HTML tables. It feels a bit like writing code in 1999, but it's the only reliable way to create columns on GitHub.

<table>
  <tr>
    <td width="50%">
      <h3>Backend Stack</h3>
      <ul>
        <li>Node.js & Express</li>
        <li>PostgreSQL DB</li>
      </ul>
    </td>
    <td width="50%">
      <h3>Frontend Stack</h3>
      <ul>
        <li>React & TypeScript</li>
        <li>Tailwind CSS</li>
      </ul>
    </td>
  </tr>
</table>

By forcing the width to 50%, you get a perfect two-column layout. I use this pattern on my main profile to separate my current tech stack from the tools I'm currently learning.

3.Centering Everything (Yes, Even Images)

Markdown naturally aligns everything to the left. But sometimes you want a big hero image right in the middle of the page, followed by a centered headline.

The standard ![]() image syntax won't let you align anything. You have to wrap your content in an align div.

<div align="center">
  <img src="hero-banner.png" alt="Project Banner" width="600" />
  <h2>My Awesome Project</h2>
  <p>A short tagline goes right here.</p>
</div>

See that width attribute on the image? That's another reason to use the HTML image tag. GitHub doesn't let you resize standard markdown images. If you upload a 2000px wide screenshot, it's going to blow up the entire page unless you constrain it with HTML.

4.The Colored Text Workaround

GitHub aggressively strips inline CSS. If you try to do <span style="color: red;">, it just ignores it entirely. So how do you add color?

You have two options.

First, if you just want to highlight code syntax, use diff blocks. Start your code block with diff, and use plus and minus signs to turn the text green or red.

```diff
+ This line will be green (good for successes)
- This line will be red (good for errors)
! This line will be orange (warnings)
# This line will be gray (comments)
```

Second, if you want colored text in regular paragraphs, you have to cheat. Some people generate small SVG images of text and embed them just to get a blue heading. But honestly? It's usually not worth the hassle. I stick to the diff trick for terminal outputs and use emojis to add pops of color in standard text. If you desperately need colored badges for your tech stack, I highly recommend using Shields.io instead of trying to hack the text colors yourself. It looks much cleaner and always scales correctly.

5.Embedding GIFs Without Killing Performance

A short GIF showing how your app works is infinitely better than three paragraphs describing it. I try to put a 5-second demo GIF near the top of all my major project READMEs. If you built a web app, show a screen recording of someone actually clicking a button and seeing a result.

But be careful here. I once added a 15MB 1080p GIF to a repo, and the page took ten seconds to load. Nobody is waiting that long, especially if they are browsing on their phone.

Keep your GIFs under 3MB. Resize them down to 800 pixels wide, and drop the frame rate to 15fps. You can embed them exactly like regular images. There are plenty of free tools online that will optimize a screen recording into a lightweight GIF in seconds.

<div align="center">
  <img src="demo.gif" width="600" alt="App Walkthrough" />
</div>

6.Keyboard Shortcut Styling

If you're writing documentation for a tool that uses hotkeys, don't just type "Press Ctrl + C". It gets lost in the text.

GitHub supports the HTML <kbd> tag, and it styles it automatically to look like a physical keyboard button. It looks incredibly professional and takes two seconds to write.

To exit the script, press <kbd>Ctrl</kbd> + <kbd>C</kbd>.

When you render that, it looks like a real button on the screen. I use this constantly in my setup instructions.

7.Creating Custom Anchor Links

When you create a header in markdown, GitHub automatically generates an invisible anchor link for it. If you write ## My Setup, GitHub creates a link id of #my-setup. So you can link to it by typing [Setup Instructions](#my-setup).

But sometimes their auto-generated names are messy, or you want to link to a specific image or section that doesn't have a header. Maybe you have a massive FAQ section and want a table of contents at the top. You can drop a custom anchor anywhere on the page using a blank anchor tag.

<a name="custom-location"></a>

[Jump straight to my custom section](#custom-location)

I use this to create "Back to Top" links at the bottom of really long documents. Put the empty anchor at the very top of your file, and scatter your jump links throughout the text. It saves the reader from having to scroll back up through three pages of API endpoints.

8.The Dark Mode Picture Tag

This is a newer feature, and a lot of people don't know it exists. If you have a custom logo or a diagram, it might look great on GitHub's light theme but become completely invisible for users on dark mode (which is most developers, let's be honest).

GitHub now supports the HTML picture tag with media queries for color schemes.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="white-logo.png">
  <source media="(prefers-color-scheme: light)" srcset="black-logo.png">
  <img alt="My Project Logo" src="black-logo.png">
</picture>

This tells GitHub to serve the white version of your logo to users with dark mode enabled, and the black version to everyone else. It's a small detail, but it shows you actually care about the user experience.

9.Wrapping Up

You don't need to use all of these tricks in a single README. In fact, you definitely shouldn't. A profile stuffed with tables, GIFs, and toggle buttons quickly turns into an unreadable mess.

Pick one or two techniques that solve a specific problem. Got too much text? Use a collapsible section. Need to show off a UI? Add a compressed GIF. The goal isn't to show off your formatting skills — it's to make your repository as easy to read as possible.