openapi: 3.0.2
info:
title: Links & Navigation
version: "1.0"
description: |
# Linking and Navigation in RapiDoc
RapiDoc offers several flexible ways to link and navigate within your API documentation and to external resources:
- **Internal Deep Links**: Jump directly to sections, tag groups, individual operations, or headings using Markdown anchor links.
- **External Links**: Link out to external websites, developer guides, SDK repositories, or issue trackers.
- **Custom HTML Links & Buttons**: Embed styled links and action buttons into slots (`header`, `footer`, `nav-logo`, or the default slot).
- **Navigation Bar Heading Links**: Automatically convert Markdown headings in the API description into interactive sidebar navigation items.
---
## Internal Deep Links
RapiDoc automatically generates consistent, predictable element IDs for every key section, tag group, and API operation. You can reference these IDs in standard Markdown link syntax (`[Label](#element-id)`) to create deep-linking shortcuts.
### ID Generation Rules
| Target Section | Generated Element ID | Formatting Rule |
| :--- | :--- | :--- |
| **Overview** | `overview` | Static ID for the API title, version, and description section. |
| **API Servers** | `servers` | Static ID for the server selection panel. |
| **Authentication** | `auth` | Static ID for security schemes and auth configuration. |
| **Tag Group** | `tag--{tag-name}` | Prefix `tag--` followed by the tag name. Characters `[\s#:?&={}]` become hyphens (`-`). |
| **Path / Operation** | `{method}-{path}` | Lowercase HTTP method followed by path. Characters `[\s#:?&={}]` become hyphens (`-`). |
| **Overview Headings** | `overview--{heading-slug}` | Prefix `overview--` followed by GitHub-slugger formatted heading text. |
> **Note on Character Replacement:** Any characters that could interfere with URL hashes or CSS selectors (specifically spaces, `#`, `:`, `?`, `&`, `=`, `{`, and `}`) are automatically replaced by a single hyphen (`-`).
### Examples of Generated IDs
- Operation `GET /users/{userId}` becomes `get-/users/-userId-` *(curly braces `{` and `}` around the path parameter are replaced by hyphens)*
- Operation `POST /users` becomes `post-/users`
- Tag group `Users` becomes `tag--Users`
- Tag group `User Management` becomes `tag--User-Management`
### Markdown Link Syntax
Use standard Markdown anchor syntax (`[Link Text](#element-id)`) anywhere inside your OpenAPI markdown descriptions:
```markdown
[Jump to API Servers](#servers)
[View Tag Group: Users](#tag--Users)
[Operation: Get Single User](#get-/users/-userId-)
[Operation: Create User](#post-/users)
```
Try clicking these live links:
- [Jump to API Servers](#servers)
- [Jump to Users Tag Group](#tag--Users)
- [Jump to Operation: Get Single User](#get-/users/-userId-)
- [Jump to Operation: Create User](#post-/users)
When clicked, RapiDoc automatically updates the browser's URL hash, expands the targeted operation or section if collapsed, and smoothly scrolls it into view across all render modes (`read`, `view`, and `focused`).
---
## External Links
Just like internal deep links, you can link to external websites, documentation, or portals using standard Markdown link syntax:
```markdown
[Visit RapiDoc Documentation](https://rapi-doc.github.io/RapiDoc)
[View RapiDoc on GitHub](https://github.com/rapi-doc/RapiDoc)
```
Live external links:
- [Visit RapiDoc Documentation](https://rapi-doc.github.io/RapiDoc)
- [View RapiDoc on GitHub](https://github.com/rapi-doc/RapiDoc)
---
## Custom HTML Links via Slots
For richer presentation or corporate branding, RapiDoc allows you to inject custom HTML elements into designated Web Component slots. Unlike Markdown links, HTML links can be styled with custom CSS classes, colors, fonts, icons, and flexbox layouts.
| Slot Name | Placement | Common Use Cases |
| :--- | :--- | :--- |
| `(default)` | Top of the main canvas | Quick-jump banners, release announcements, or action buttons. |
| `header` | Right side of top header bar | Navigation buttons, GitHub links, or environment selectors. |
| `footer` | Bottom of document canvas | Copyright notices, terms of service, and support contacts. |
| `logo` | Top-left of header | Custom company brand logo with a link to your home portal. |
| `nav-logo` | Top of sidebar navigation | Sticky sidebar branding with an interactive link. |
### Slot Usage Example
```html
```
Check out the top-right corner of this demo page for an example of custom styled **HTML Links** injected via slots.
---
## Headings as Navigation Links
You can automatically promote **level-1 (`#`) and level-2 (`##`) Markdown headings** from your `info.description` into interactive sidebar navigation links by setting the `info-description-headings-in-navbar="true"` attribute:
```html
```
Check out the sidebar navigation bar on this demo page: each major heading from this overview is listed under the Overview section, allowing readers to jump directly to any topic!
servers:
- url: https://reqres.in/api/
tags:
- name: Users
description: Operations related to creating and retrieving user profiles.
paths:
/users:
get:
tags:
- Users
description: List of users (paginated)
parameters:
- name: page
in: query
schema:
type: integer
example: 2
- name: delay
in: query
description: for simulating response delay. Do not provide any value for page parameter(0 indicates no delay)
examples:
- '0'
- 3
schema:
type: integer
minimum: 0
maximum: 10
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: object
description: Description of **User** object
properties:
page:
description: Current Page number
type: integer
per_page:
description: Number of records per page
type: integer
total:
description: Total number of records
type: integer
total_pages:
type: integer
data:
type: array
description: List of users
items:
$ref: '#/components/schemas/user'
support:
$ref: '#/components/schemas/support'
post:
tags:
- Users
description: Create a user
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/userInput"
responses:
201:
description: User creation response
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/userInput'
- $ref: '#/components/schemas/createUserResponse'
/users/{userId}:
get:
tags:
- Users
description: Get a Single User
parameters:
- in: path
name: userId
schema:
type: integer
example: 3
required: true
description: Numeric ID of the user to get
responses:
200:
description: Response when a user is found
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/user'
support:
$ref: '#/components/schemas/support'
404:
description: User Not found
components:
schemas:
user:
type: object
properties:
id:
description: User ID
type: integer
email:
description: User Email
type: string
first_name:
description: First Name
type: string
last_name:
description: Last Name
type: string
avatar:
description: Avatar URL
type: string
support:
type: object
properties:
url:
description: Support URL
type: string
text:
description: Support URL - Description
type: string
userInput:
type: object
properties:
name:
description: User Name
type: string
job:
description: Job
type: string
createUserResponse:
type: object
properties:
id:
type: integer
createdAt:
type: string