From 4fa4347ac453300c6028a5550ab46eb9612c414e Mon Sep 17 00:00:00 2001 From: grossyoan Date: Mon, 9 Feb 2026 11:50:45 +0100 Subject: [PATCH] topics: mention about external references added --- src/_help/documentation-experience/topics.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/src/_help/documentation-experience/topics.md b/src/_help/documentation-experience/topics.md index 42a39e4c..4110fac7 100644 --- a/src/_help/documentation-experience/topics.md +++ b/src/_help/documentation-experience/topics.md @@ -31,6 +31,22 @@ x-topics: ``` ``` +## External references + +You can write your topics in dedicated Markdown files to keep your OpenAPI definition file clean. To reference a Markdown file, add a `$ref` link inside the `content` object of your topic. + +```yaml +x-topics: + - title: Getting started + content: + $ref: ./getting-started.md + - title: Authentication + content: + $ref: ./authentication.md + example: + $ref: ./authentication-example.md +``` + ## Public documentation examples Here are some examples of public documentation made by teams using `x-topics`: