Skip to content

Commit aff04d7

Browse files
cdervcderv
authored
[Sync to prerelease] docs: document image-alt levels and page-level image options (#2292)
The `image-alt` key at its different levels was undocumented outside about pages and listing items, though Quarto reads all of them for the og:image:alt and twitter:image:alt tags. Add an `image-alt` row to the Twitter Card and Open Graph tables, and describe in Preview Images where the alt text comes from: the page's `image-alt` next to `image`, `website: image-alt` for the site-level image, the image's own alt text when the preview image is found in the page, and a per-service override. About pages fall back to the document-level `image-alt` and `image-title`, and a page's `image-lazy-loading` overrides the listing option for that page's item. Say so in the about and listings pages. (cherry picked from commit a0411c6)
1 parent eebb1a3 commit aff04d7

3 files changed

Lines changed: 11 additions & 0 deletions

File tree

‎docs/websites/website-about.qmd‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,8 @@ about:
116116
image-shape: round
117117
```
118118

119+
`image-alt` and `image-title` can also be set at the document level, next to `image`. Values under `about` take precedence.
120+
119121
### Links
120122

121123
Your about page also may contain a set of links to other resources about you or your organization. Each template will render these links in a slightly different way. Here are the options that you can specify for each link:

‎docs/websites/website-listings.qmd‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -198,6 +198,8 @@ It is possible to customize the appearance of listings using the following optio
198198
| | ``` |
199199
+--------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
200200
| `image-lazy-loading` | When `true`, listing images are loaded only as they come into view. When `false`, images are automatically loaded. Default: `true` |
201+
| | |
202+
| | A page can override this for its own item by setting `image-lazy-loading` in its front matter. |
201203
+--------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
202204
| `max-description-length` | The maximum length of the description displayed in the listing (in characters). Defaults to 175. |
203205
+--------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

‎docs/websites/website-tools.qmd‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,8 @@ You may also provide additional metadata to be used when generating the Twitter
102102
| | |
103103
| | If `image` is not provided, Quarto will automatically attempt to locate a preview image. For more information, see [Preview Images]. |
104104
+---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
105+
| `image-alt` | Alternative text for the preview image. By default, Quarto uses the alt text that goes with the preview image. For more information, see [Preview Images]. |
106+
+---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
105107
| `card-style` | Either `summary` or `summary_large_image`. If this is not provided, the best style will automatically selected based upon other metadata. You can learn more about Twitter Card styles [here](https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/abouts-cards). |
106108
+---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
107109
| `creator` | `@username` of the content creator. Note that strings with special characters such as `@` must be quoted in yaml. |
@@ -145,6 +147,8 @@ You may also provide additional metadata to be used when generating the Open Gra
145147
| | |
146148
| | If `image` is not provided, Quarto will automatically attempt to locate a preview image. For more information, see [Preview Images]. |
147149
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
150+
| `image-alt` | Alternative text for the preview image. By default, Quarto uses the alt text that goes with the preview image. For more information, see [Preview Images]. |
151+
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
148152
| `locale` | The locale that the Open Graph metadata is marked up in. |
149153
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
150154
| `site-name` | The name which should be displayed for the overall site. If not explicitly provided in the `open-graph` metadata, Quarto will use the `website:title` value. |
@@ -219,10 +223,13 @@ If you'd like to provide a default that is used when pages specify a preview ima
219223
```{.yaml filename="_quarto.yml"}
220224
website:
221225
image: "https://quarto.org/assets/images/quarto-dark-bg.jpeg"
226+
image-alt: "Quarto logo"
222227
```
223228

224229
With a `site-url`, a relative path in `_quarto.yml`, for `website: image` or for `image` under `website: open-graph` or `website: twitter-card`, is relative to the project directory, whichever page uses it.
225230

231+
Use `image-alt` to provide alternative text for the preview image. Set it next to `image` in the page front matter, or under `website` for the site-level default as above. `website: image-alt` is only used for pages that fall back to the site-level image. When Quarto finds the preview image in the page, it uses that image's alt text (for example, from `fig-alt`), and the page's `image-alt` if the image has none. To use different alt text for one service, set `image-alt` under `twitter-card` or `open-graph`.
232+
226233
If you would like to prevent preview image discovery on a page, set `image` to `false`:
227234

228235
```{.yaml filename="page.qmd"}

0 commit comments

Comments
 (0)