README Markdown Rendering Bug when using img "align" attribute

[donatj]

🏷️ Discussion Type

Bug

Body

You can see the issue on a real repo here: https://github.com/donatj/picopass

When you use the allowed align attribute of an img tag, ala

<img width="200" align="right" alt="Example Device" src="https://github.com/user-attachments/assets/505ece17-1a36-4fbd-b79b-e4ec3843afc2" />

headers now overlap the image.

This did not used to be a problem. I've been using images like this for many years and it broke maybe a year ago and I've been patiently awaiting it to be fixed 😆

They appear to have been made position: relative

Here is a screenshot of the issue:

---

More info

You can see here (currently, 2026-09-09) that it does not appear to be a problem rendering Markdown in community discussions. Just in READMEs

picopass

picopass is a TinyGo toy project that turns a Raspberry Pi Pico 2 W into a
physical TOTP keyboard. It gets time over Wi-Fi and NTP, then presents itself
over USB as both a serial port and an HID keyboard. Three physical buttons type
the current UTC time, a stored password, or a freshly generated TOTP code.

Not a secure authenticator

This is an experiment, not a security product. Do not use it for real
accounts or in a secure environment.

It intentionally keeps Wi-Fi credentials, a system password, and the TOTP seed
as plaintext in the committed secrets.go file. It has no encryption, secure
element, user verification, tamper resistance, access control, lockout, secure
updates, or security review. Anyone who can access the device, its firmware,
the repository, or the computer currently receiving the HID input may be able
to use or copy those credentials. HID typing can also go to the wrong focused
application. Use only disposable test credentials you are comfortable exposing.

[github-actions[bot]]

💬 Your Product Feedback Has Been Submitted 🎉

Thank you for taking the time to share your insights with us! Your feedback is invaluable as we build a better GitHub experience for all our users.

Here's what you can expect moving forward ⏩

• Your input will be carefully reviewed and cataloged by members of our product teams. 
  • Due to the high volume of submissions, we may not always be able to provide individual responses.
  • Rest assured, your feedback will help chart our course for product improvements.
• Other users may engage with your post, sharing their own perspectives or experiences. 
• GitHub staff may reach out for further clarification or insight. 
  • We may 'Answer' your discussion if there is a current solution, workaround, or roadmap/changelog post related to the feedback.

Where to look to see what's shipping 👀

• Read the Changelog for real-time updates on the latest GitHub features, enhancements, and calls for feedback.
• Explore our Product Roadmap, which details upcoming major releases and initiatives.

What you can do in the meantime 💻

• Upvote and comment on other user feedback Discussions that resonate with you.
• Add more information at any point! Useful details include: use cases, relevant labels, desired outcomes, and any accompanying screenshots.

As a member of the GitHub community, your participation is essential. While we can't promise that every suggestion will be implemented, we want to emphasize that your feedback is instrumental in guiding our decisions and priorities.

Thank you once again for your contribution to making GitHub even better! We're grateful for your ongoing support and collaboration in shaping the future of our platform. ⭐

[tw4]

Close, but it is not the heading element itself - that one is still position: static. What changed is that GitHub now wraps every heading in <div class="markdown-heading"> (it carries the anchor-link icon), and that wrapper is position: relative. A positioned box paints after floats, so it lands on top of your image instead of behind it.

The part that actually overlaps is the heading's bottom rule, not its text. h1 and h2 in markdown-body carry a border-bottom, and a block box's border spans the full container width - a float shortens line boxes, not block boxes. So your paragraphs wrap correctly and only the rule draws straight across the photo. On your README it is the "Not a secure authenticator" rule crossing the image.

Two workarounds that hold up today:

1. Use ### for the headings that sit beside the floated image. h3 through h6 have no border-bottom at all, so there is nothing left to draw over it:

<img width="200" align="right" alt="Example Device" src="..." />

### Not a secure authenticator

2. Or drop the float and use a two-column table if you want to keep ##:

<table>
<tr>
<td>

## Not a secure authenticator

Markdown still renders inside the cell as long as you keep the blank lines around it.

</td>
<td width="220"><img width="200" alt="Example Device" src="..." /></td>
</tr>
</table>

And that is also why it looks fine here: comment bodies are rendered without the markdown-heading wrapper, so the headings in a discussion are plain non-positioned elements. Same Markdown, different rendering path.