Where should image captions and alternative text be maintained in Busa CMS?

Question

I’m preparing an illustrated article in Busa CMS. Some images need a visible caption, while others need alternative text describing their content. How should these be written in the Markdown body, and which parts depend on the website renderer? I’d like to understand the distinction before formatting the article.

Kelly · Answer

In Busa CMS, keep **both** in the Markdown **body**: put **alternative text** inside the image syntax, and put the **visible caption** as ordinary Markdown (or a figcaption) **next to** the image. CMS stores the Markdown; your **website renderer** decides how caption and alt are displayed on the page.

## What goes where

| Need | Where in Markdown | Who uses it |
|------|-------------------|-------------|
| **Alternative text** (accessibility / when image fails) | `

![Alternative text here](https://…/image.png)

` — the `[…]` brackets | Screen readers; `img alt` in HTML |
| **Visible caption** (readers see under / beside the image) | A line under the image, e.g. `*Photo: factory floor, 2026*` or a `figure` / `figcaption` block if your renderer supports it | On-page readers |

![](https://s1.busabase.com/attachments/cHEfVIklx0ASY7gZ6iJhU7wCONhhfJNb/blobs/sha256/60/6006df02d0d261aff35082a0dc1f2d1e0deec10515d5a029059f1376940bc76b.png)

*Diagram · alt in `![…]` vs visible caption below*

### Example

```markdown
![Line chart of monthly signups, January to June](https://…/chart.png)

*Local demo / Diagram — monthly signups*
```

- Alt: concise description of the image content (not the same as SEO title).  
- Caption: what you want sighted readers to see (credit, short explanation, or “diagram” label).

## What depends on the website renderer

Busa CMS **stores** the Markdown body; the **site** (Safe Markdown / your Next components) turns it into HTML:

1. Standard `![alt](url)` → an `<img alt="…">` (alt is usually **not** shown as visible text).  
2. The italic / paragraph / `figcaption` you wrote → visible caption **only if** the theme styles that Markdown as a caption.  
3. If the front-end replaces Markdown images with a custom component, caption rules follow **that** component — check your site’s article template once.

Cover images and CMS fields such as SEO title are separate from inline body images; they do not replace `alt` / caption inside the article body.

## How to verify

1. In CMS, set a distinct alt string and a distinct caption line; publish / preview.  
2. View page source or inspect the image: `alt` should match the bracket text.  
3. On the page, confirm the caption line is visible where your theme places it.  
4. If caption text appears only in the Markdown editor but not on the site, the gap is in the **renderer / theme**, not in missing CMS fields.

## Boundaries

- Do not put the long visible caption only inside `![…]` and expect it to show on the page — many themes hide `alt`.  
- Do not leave `![](url)` empty alt on informative images; use a short description or mark decorative images deliberately.  
- Asset library metadata is for the file; **article-specific** wording still belongs in that article’s Markdown.

If you tell us whether the site uses the standard Busabase CMS Markdown helpers or a custom image component, we can mirror the exact caption pattern that theme already styles.

What goes where

Example

What depends on the website renderer

How to verify

Boundaries

Your reply