Skip to content

API explorer: mark deprecated operations in the sidebar and in search - #4668

Open
reakaleek wants to merge 10 commits into
mainfrom
deprecate-ops-nav-search-84a4890c
Open

reakaleek wants to merge 10 commits into
mainfrom
deprecate-ops-nav-search-84a4890c

Conversation

@reakaleek

Copy link
Copy Markdown
Member

Why

What

  • A deprecated operation's sidebar row shows a struck-through, dimmed title and a grey method chip, in both the legacy and the design-system look. Screen readers hear "Deprecated" after the title.
  • A deprecated search result gets the same strike-through and grey chip, plus the page's outlined Deprecated badge beside the title.
  • The navigation search API returns deprecated for each hit, and one ApiOperation.Deprecated accessor feeds the page, the overview rows, the sidebar and the index.

Notes

  • Rows and results that are not deprecated render byte-identical to main. The visual check against main shows no diffs, and a nav tree's content hash only changes when the tree contains a deprecated leaf.
  • The sidebar row gets no extra chip on purpose: rows already wrap beside a single method chip at tablet width.
  • Search ranking is unchanged. A down-weight for deprecated operations is a possible follow-up.

🤖 Generated with Claude Code

reakaleek and others added 10 commits November 3, 2026 22:45
`ApiOperation.Deprecated` is now the one fact that the page badge, the
overview rows, the search exporter and the sidebar read. The renamed
`IApiOperationNavigationModel` exposes it, and `NavigationRenderNode`
projects it. The tree hash includes it only when set, so trees without a
deprecated leaf keep their cached `nav-tree-<hash>` id.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A reader now sees that an operation is deprecated before opening it.
The row keeps its width: the title is struck through and dimmed like a
deprecated property, the method chip turns grey, and a hidden word keeps
the link name honest for screen readers. Rows that are not deprecated
render the same markup as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The design-system tree now marks a deprecated operation the same way as
the legacy sidebar. One `nav-tree__link--deprecated` modifier strikes the
title and greys the method badge through its tone tokens. A hidden word
names the state for screen readers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The index already stores `api.deprecated`, but the `_source` filter left
it out and the response had no field for it. Navigation search results
now carry `deprecated`, which is false for docs pages, so the search
card can mark a deprecated operation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A reader who finds a deprecated operation in search now sees the same
red "Deprecated" badge that its page shows, before clicking through.
The card reuses the global `.deprecated-badge` class. The schema keeps
`deprecated` optional, so an API and a frontend deployed at different
times still parse each other.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…dge markup

The search card reused the filled chip the explorer draws on deprecated
parameters, so the same word looked different from the badge on the page
it links to. The card now emits the title badge's own classes and inherits
its outlined look from the same rules.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…an arguments

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…o the chip's height

A search card now treats a deprecated operation like its sidebar row: the
title is struck through and dimmed and the method chip turns grey. The
page's outlined Deprecated badge stays beside the title, sized like the
method chip so it sits inside the title line instead of stretching the row.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The badge wrapper inherited the title's 24px line height and aligned its
content to the bottom of that box, so the badge sat 3.5px below the text
centre. As an atomic inline with its own line height it centres within 1px
and still stops the row's hover underline at the title text.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@reakaleek

Copy link
Copy Markdown
Member Author
image image

@github-actions

github-actions Bot commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

Docs preview (local build)

Handbook preview: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/4668/

Sample changed pages:

This branch was successfully deployed

2 active deployments
docs-preview — 9667e979 Deployed Nov 3, 2026 by github-actions[bot]
assembler-preview — 9667e979 Deployed Nov 3, 2026 by github-actions[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant