posit-dev / posit-dev/open-source-website
Unify image alt text and caption syntax across .qmd and .md posts
Nobody has claimed this yet.
- Dominant language
- HTML
- Stars
- 55
- Forks
- 24
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 17
Description
Currently, authors need to remember different syntax for alt text and captions depending on whether they're writing a .qmd or .md post:
.qmd posts
Alt text uses the fig-alt attribute, caption goes in []:
{fig-alt="Alt text"}
But fig-alt renders to data-fig-alt in the hugo-md output — not to alt — so the alt text is lost for screen readers. (Tracked upstream)
.md posts
Alt text goes in [], caption uses a title string:

Ideal state
Authors shouldn't need to think about which format they're in. We should find a way to make image accessibility and captions work consistently across both formats — ideally with a single syntax, or at minimum with a render hook or shortcode that normalises the output.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Compare how image syntax is rendered in .qmd and .md posts, focusing on the Hugo-md output and the reported data-fig-alt result. Investigate whether a render hook or shortcode can normalize captions and alt text, then verify that both formats produce consistent captions and accessible alt attributes for screen readers.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- hugo, markdown
- Domain
- accessibility, content
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100