Add deprecated indicator to all deprecated API reference pages#2070
Open
Add deprecated indicator to all deprecated API reference pages#2070
Conversation
Create a reusable DeprecatedWarning snippet and include it on all 120 API reference pages nested under the Deprecated navigation group. This makes deprecation status visible in the page content itself (not just the sidebar), which is critical for AI agents and screen readers that don't parse navigation DOM. Replaces ad-hoc Tip callouts on botusers and tunnels pages with the standardized warning component. Closes DOC-569
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Unrelated to the deprecation warning feature — these are pre-existing
style issues ("traffic policy" -> "Traffic Policy", "agent endpoints"
-> "Agent Endpoints") flagged by Vale because our previous commit
touched these files. Feel free to drop this commit if you'd prefer to
keep the PR scoped to the deprecation warning only.
BPKelley
added a commit
to ngrok/ngrok-openapi
that referenced
this pull request
Mar 25, 2026
Adds the OpenAPI `deprecated: true` field to all deprecated operations (Bot Users, Backends, Edges, Tunnels) so that Mintlify and other consumers can render deprecation indicators natively. Companion to ngrok/ngrok-docs#2070. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
3 tasks
Contributor
Author
|
FYI this other PR is probably a better approach: ngrok/ngrok-openapi#17 If it's correct, we can probably just reject this current PR |
Collaborator
|
@BPKelley It looks like the warnings aren't rendering in the preview deployment. Maybe these generated pages don't support importing custom components? Could you test just pasting the warning on one of the pages? I'll ask mintlify if this is a limitation |
sg-writer
added
kind/enhancement
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
DeprecatedWarningsnippet (snippets/api/deprecated-warning.mdx) using the<Warning>callout component<Tip>callouts on botusers and tunnels pages with the standardized componentWhy
Deprecation status is only visible in the sidebar nav grouping — not in the page content itself. AI agents and LLMs reading these pages have no way to know the endpoint is deprecated, causing them to repeatedly suggest deprecated APIs (Edges, Tunnels, Bot Users) in new integrations and specs.
Prior art:
universal-gateway/edges.mdx,agent/config/v3.mdx, andsnippets/shared/warnings/traffic-policy-preview.mdxall use this same<Warning>pattern.Closes DOC-569