1. The Broken Camo Proxy Image (Red 'X' or 504 Gateway)
Symptoms:
Your stats cards or badges show a broken image placeholder on GitHub, but open perfectly when you paste the URL directly into a new browser tab.
Root Cause:
GitHub routes all external media through Camo (camo.githubusercontent.com). If the host server takes longer than 4.0 seconds to respond or has an incomplete SSL certificate chain, Camo aborts and permanently returns a cached 504 error.
The Fix:
Add &cache_seconds=86400 to your card URLs. This allows the host server to respond with pre-cached edge bytes in under 200ms, well within Camo’s timeout budget.
2. Raw HTML Tags Leaking as Plain Text
Symptoms:
Instead of rendering a table or centered paragraph, GitHub literally displays <p align="center"> as visible text on the screen.
The Fix:
GitHub’s Markdown parser requires an empty blank line between any preceding Markdown content (headings, lists, text) and raw HTML opening tags. Always leave a full blank line before opening <p>, <table>, or <div>.
3. The Unencoded Hash in Shields.io Hex Colors
Wrong: https://img.shields.io/badge/Next.js-#000000
Correct: https://img.shields.io/badge/Next.js-000000
In URI standards, # marks an anchor. When your browser requests the URL, it truncates the hex color at the hash mark, causing Shields.io to return an invalid badge color error.
4. Disappearing CSS: Why inline `style=` Fails
Many developers try to style tables using standard HTML/CSS:
<!-- ❌ Stripped completely by GitHub sanitizer --> <div style="display: flex; justify-content: space-between; border-radius: 12px;">
GitHub's HTML sanitizer strips all style attributes unconditionally. To create column layouts, you must use HTML table attributes:
<!-- ✅ Allowed and fully rendered by GitHub -->
<table width="100%">
<tr>
<td width="50%" valign="top">Column 1</td>
<td width="50%" valign="top">Column 2</td>
</tr>
</table>5. The 4-Space Accidental Code Block
In standard Markdown, indenting any line with four spaces or a tab turns that line into a raw monospace code block. If you indent an HTML tag or list item with four spaces for visual code organization, GitHub will render the raw markup inside a gray box instead of parsing it.
Generate Bug-Free Markdown with ProfileCrest
ProfileCrest’s compiler automatically validates HTML sanitization, hex escaping, and Camo caching so your README renders flawlessly every time.
🚀 Open ProfileCrest Generator