a11y: `quarto create project blog` scaffold has images with no alt text and icon-only navbar links with no name

未關閉
  • 哪裡不對？
#15,038 0 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視

維護者通常 1 天內回覆

還沒有人認領這個 Issue。

評估

難度
3/5
預估耗時
半天
新手友好度
72/100
Issue 類型
缺陷
描述清晰度
描述清楚
活躍度
活躍
技術堆疊
markdown, typescript, yaml
領域
accessibility, tooling

研究方向

Start with the blog scaffold content in src/project/types/website/website.ts and the template src/resources/projects/website/templates/blog/_quarto-blog.ejs.yml. The scaffold files to edit are about.qmd, posts/post-with-code/index.qmd, posts/welcome/index.qmd and the navbar in _quarto.yml, where the GitHub and Bluesky icon links need aria-label. Done when quarto create project blog, render and quarto call axe report no image-alt or link-name findings.

由索引模型根據 Issue 內容生成。

描述

accessibility html

The blog scaffold from quarto create project blog fails WCAG 2.x Level A
right after it is created. It has three images with no alternative text and
two icon-only navbar links with no accessible name. The templates already
support all the fixes. The scaffold content does not use them.

New authors copy the scaffold as their model, so it should show the
accessible pattern.

Reproduce (Quarto 1.11.5)

quarto create project blog blog
quarto render blog
quarto call axe blog/_site

axe-core 4.10.3, 4 pages, 1440x900 and 320x568:

Rule (WCAG) Element Source in scaffold
image-alt (1.1.1) <img class="about-image"> on about.html about.qmd: image: profile.jpg, no image-alt
image-alt (1.1.1) listing thumbnail, Post With Code posts/post-with-code/index.qmd: image: "image.jpg", no image-alt
image-alt (1.1.1) <img> in Welcome post body, and its listing card posts/welcome/index.qmd: ![](thumbnail.jpg)
link-name (2.4.4, 4.1.2) both listing thumbnail links (an image link with no alt has no name) follows from the two rows above
link-name (2.4.4, 4.1.2), role-img-alt (1.1.1) navbar GitHub and Bluesky links, every page _quarto.yml: - icon: github / - icon: bluesky with no text or aria-label

Proposed scaffold changes

All in src/project/types/website/website.ts (blog scaffold content) and
src/resources/projects/website/templates/blog/_quarto-blog.ejs.yml.

_quarto.yml:

  navbar:
    right:
      - about.qmd
      - icon: github
        href: https://github.com/
        aria-label: GitHub
      - icon: bluesky
        href: https://bsky.app/
        aria-label: Bluesky

about.qmd:

image: profile.jpg
image-alt: "A stick figure drawn in light against a dusk sky"

posts/post-with-code/index.qmd:

image: "image.jpg"
image-alt: "City lights across Earth at night, seen from orbit"

posts/welcome/index.qmd:

![](thumbnail.jpg){fig-alt="A laptop, a cup of coffee, a notepad and a phone on a wooden desk"}

Result

The same scan with all four changes: every image-alt, link-name and
role-img-alt finding is cleared (10 findings → 0). The findings that
remain have their own issues: listing category contrast (#14381) and the
best-practice landmark and heading-order findings
(#14375/#14377/#14384/#14605).

Other quarto create scaffolds

We checked the 1.11.5 project templates (default, website, book,
manuscript, confluence). Only the blog sets image: or uses icon-only
navbar items. The book scaffold copies cover.png into the project, but
its _quarto.yml does not set cover-image, so nothing renders it. When
an author adds cover-image, they need cover-image-alt too. This is
outside the scope of this issue.

Related

  • #14828: navbar: tools: / sidebar: tools: with only icon: get
    aria-label="". That path is a different template (navtools.ejs).
    The blog's navbar: right: items go through navitem.ejs/navicon.ejs.
    There, aria-label: already works, but there is no fallback when it is
    not set. The icon-name fallback proposed in #14828 should also cover
    this path. This issue only changes the scaffold, so the blog is correct
    with or without that fallback.
  • #7979 (closed 2023-12): added image-alt support to about pages. The
    scaffold was not updated to use it.
  • #7028: listing image alt.
主要語言
JavaScript
星號
6.1k
分支
478
平均合併
17 小時 7 分鐘
30 天內合併 PR
112

環境準備

從這裡開始

  1. 先讀完整個 Issue，再讀專案的貢獻指南。
  2. 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
  3. Fork 儲存庫，在一個分支上完成修改。
  4. 送出 Pull Request，並在描述裡引用這個 Issue 編號。

quarto-dev/quarto-cli 的其他 Issue

查看 quarto-dev/quarto-cli 的全部 Issue

相似的 Issue

更多 JavaScript Issue

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。