Right floating image in GitHub’s README.md

by

Summary

This incident examines why right‑floating images in GitHub README.md behave unpredictably, especially when placed near Markdown headings. GitHub’s Markdown renderer mixes Markdown and sanitized HTML, which leads to layout collisions such as header underline borders overlapping floated images.

Root Cause

The underlying issue is that GitHub’s Markdown engine (CommonMark + HTML sanitization) does not fully support traditional HTML float behavior inside Markdown blocks.

Key factors include:

  • Markdown headings generate block-level elements with CSS borders that do not respect HTML float boundaries.
  • Floated HTML elements are not wrapped by the Markdown parser, causing the heading’s underline to overlap the image.
  • GitHub strips or restricts CSS, preventing custom styling that would normally fix the issue.
  • Paragraph wrappers (<p align="right">) break the float, forcing the image onto its own line.

Why This Happens in Real Systems

Real-world Markdown renderers often:

  • Combine multiple rendering engines (Markdown → HTML → CSS) that don’t share layout rules.
  • Apply strict sanitization for security, removing CSS that would normally control floats.
  • Use opinionated CSS that prioritizes readability over layout flexibility.
  • Treat HTML as a “best effort” feature rather than a fully supported layout tool.

Real-World Impact

Engineers encounter:

  • Unexpected overlaps between images and headings.
  • Broken layouts when mixing Markdown and HTML.
  • Inconsistent rendering between GitHub, VS Code preview, and other Markdown viewers.
  • No reliable way to float images without CSS.

Example or Code (if necessary and relevant)

A minimal reproduction of the failure:



## My Header

This causes the header underline to overlap the image because the float is not respected by GitHub’s CSS.

How Senior Engineers Fix It

Experienced engineers avoid floats entirely and use layout-safe alternatives:

  • Use tables to position images without floats.
  • Place images below headings, not beside them.
  • Use Markdown’s natural flow instead of forcing HTML layout.
  • Use shields/badges, which are designed to align inline without floats.
  • Accept GitHub’s limitations and design for consistency across renderers.

A common workaround:

|  | Text starts here |
| --- | --- |

This avoids floats and renders consistently.

Why Juniors Miss It

Less experienced engineers often assume:

  • GitHub Markdown behaves like full HTML.
  • The align attribute still works reliably (it’s deprecated).
  • Floats will behave the same as in a normal webpage.
  • Markdown and HTML can be mixed without side effects.

They don’t yet recognize that GitHub README.md is not a general-purpose webpage, and its renderer intentionally restricts layout control.

Key takeaway: GitHub README.md is a constrained environment—if you need layout control, floats are the wrong tool.

Leave a Comment