Linking operations

Guides mention operations all the time. Instead of copying URLs, link to an operation by its id. The link follows the operation, and orbitdocs build fails if the operation is renamed or removed.

Link with op:Copy Anchor Link

Write a normal Markdown link whose target is op:<api id>/<operation id>:

Find a flight with [Search flights](op:demo/search-flights), then
[create a booking](op:demo/create-a-booking).

It renders as: Find a flight with Search flights, then create a booking.

The link goes to /reference/demo/search-flights/, with the base path added. To link to the top of an API's reference, leave out the operation: [the API reference](op:demo).

Show the method and path with EndpointCopy Anchor Link

<Endpoint> renders the operation's method badge and path, linked to the operation:

Create the booking with <Endpoint api="demo" op="create-a-booking" />.

Create the booking with POST /v1/bookings.

The props can come in any order and with either kind of quotes. orbitdocs check reads api="…", api='…' and api={"…"}; a prop set from a variable (api={id}) is only checked when the page renders.

Find an operation's idCopy Anchor Link

The operation id is the last part of its reference URL. Open the operation in the reference and copy it from the address bar:

/reference/demo/create-a-booking/
           ^^^^ ^^^^^^^^^^^^^^^^
           api id   operation id

How ids are made:

• From a Nest app, the id is the operation's title in kebab case: Create a booking becomes create-a-booking. See Decorators.
• From a spec file or URL, the id comes from the spec's operationId, lowercased, with other characters turned into -. getPetById becomes getpetbyid and list_pets becomes list-pets. Without an operationId, the summary is used.

The ids of an API are also listed in openapi/<api id>.json as each operation's operationId.

Let the build check your linksCopy Anchor Link

orbitdocs check reads every .md and .mdx file in content/ (guides) and reference/ (operation, group and API content) and reports:

npx orbitdocs check

✗ content/quickstart.mdx: link op:travel/create-booking does not exist
✗ 1 problem(s).

orbitdocs build runs the same check after extraction and stops on any problem. Links inside code blocks and inline code are ignored, so you can show examples.

GotchasCopy Anchor Link

• Ids are lowercase. op: targets must use lowercase letters, digits and -, like the ids themselves.
• The check needs the specs. Run orbitdocs extract first, or use orbitdocs build, which does both.

Next stepsCopy Anchor Link