# Markdown Overlays

Overlays let editors replace rendered descriptions without changing the uploaded specification. The source document stays untouched, and the overlay survives new versions. This page explains what can be overlaid and how.

> **Roles:** Creating, editing and deleting overlays is for `admin` and `editor`. Every user can use the **Show Original** toggle. Users who are not administrators need access to the service through a team.

## What you can overlay

| Target | What changes |
|--------|--------------|
| Service | The description on the service page |
| Tag | The label and description of a tag page, also the label in the left menu |
| Endpoint or method | The title and the description |
| Parameter or field | The description of a request parameter, a nested property or a response field |

An endpoint or tag without a custom title keeps showing its default: the tag name, or the endpoint's summary, `operationId` or method and path. Leaving the **Title** field blank on save clears an existing custom title without touching the description. **Delete overlay** removes both.

The title is a single line of plain text, shown as-is. The description is Markdown.

## Editing an overlay

Open the service, tag or endpoint page and use its overlay edit button. The editor is one bordered block made of a toolbar, the text area and a status bar.

- The toolbar has a **Heading** menu (levels 1–6), bold, italic, inline code, code block, quote, horizontal rule, bulleted and numbered lists, link and image, and a button switching between Markdown and Visual editing.
- The status bar shows the current mode and a Unicode character count. An editor with a size limit shows it in bytes and turns red when the text is over.

## Show Original

A page with an active overlay has a **Show Original / Show Overlay** toggle. It lets anyone compare the overlay with the pre-overlay text. It is visual, per page and never stored.

## Parameter and field overlays

Open a parameter's description with the info button of its row. Editors also get the button for parameters that have no description. The dialog offers **Edit**, **History** and **Show original**. Readers only get the toggle. A dot on the button marks a description that is an overlay.

This works for nested properties too (such as `filter.status`, array items or a request body field) and for the fields of a response, including an OpenRPC result.

- The history keeps the last 50 versions per parameter. **Restore** makes an older text the current one, and saving an empty text deletes the overlay together with its history.
- Concurrent edits are detected: if someone else saved in between, the save is refused.
- Only fields can be overridden, not the response itself or the root schema.

## Overlays survive changes in the specification

Overlays are tied to the names the specification uses: operation id, tag name, parameter position. If a later version removes or renames what an overlay refers to, the overlay is moved to **Orphaned overlays** instead of being deleted. Administrators and editors review them from **Orphaned** in the top menu and delete the ones they no longer need. They are never deleted automatically.

## Where overlays apply

Overlays are applied to the merged documentation, so they appear in the interface, in the MCP server (if the token allows overlay text) and, when the overlay option is on, in exports. See [Export Wizard](/documentation/export-wizard).

## Next steps

- [Endpoint Pages](/documentation/endpoint-pages)
- [Service Structure](/documentation/service-structure)

---
Source: https://selfdochub.com/documentation/markdown-overlays
