posit-dev / posit-dev/open-source-website

Unify image alt text and caption syntax across .qmd and .md posts

Open
#154 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

blog
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 []:

![Caption](image.png){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:

![Alt text](image.png "Caption")
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.