Reference links are out of scope if they are not defined within a 2nd-level markdown sub-heading

[mm-gmbd]

openapi: 3.0.0
info:
  title: A Title
  version: A Version
  description: |-
    # Some Markdown

    With a [reference link][ref-link].

    <!-- reference links -->

    [ref-link]: https://somewhere.com

The use of reference links is extended Markdown, but supported in many renderers. However, Redoc seems to ignore this syntax and simply uses the text, as is, in the rendered document (though the reference links themselves at the bottom are not rendered).

As a matter of fact, I'm using reference links in this GH comment:

The use of [reference links][link-to-reflinks] is...

[link-to-reflinks]: https://sourceforge.net/p/reuseproject/discussion/markdown_syntax#md_ex_reflinks

I haven't tested this with individual operation descriptions (or anywhere else Markdown is intended to be used), but this does not currently work in the main info.description block.

[mm-gmbd]

Actually, I think this may only happen if the link is broken onto multiple lines (just tested the repro provided above and it actually worked as intended)...

The following updated YAML will successfully repro the issue.

openapi: 3.0.0
info:
  title: A Title
  version: A Version
  description: |-
    # Some Markdown

    With a [reference 
    link][ref-link].

    <!-- reference links -->

    [ref-link]: https://somewhere.com

[mm-gmbd]

After further investigation, I was wrong on both repros (sorry about that), but my issue actually comes with how Redoc parses reference links in such a way where they are tied to a particular section of the document.

Apparently, reference links are tied to a 2nd-level heading, and when a new 2nd-level heading is defined, they are no longer "in scope".

Take the markdown (and plug it into info.description):

# Main

Overview. What is going on [link][going-on-link].

## Subsection1

Subsection1. What is going on [link][going-on-link].

## Subsection2

Subsection2. What is going on [link][going-on-link].

## Subsection3

Subsection3. What is going on [link][going-on-link].

### Subsection3Section1

What is going on [link][going-on-link].

[going-on-link]: https://bing.com

## Subsection4

Subsection4. What is going on [link][going-on-link].

### Subsection4Section1

Subsection4Section1. What is going on [link][going-on-link].

[going-on-link]: https://google.com

This renders as follows:

The links in Subsection3 and Subsection3Section1 are to bing.

The links in Subsection4 and Subsection4Section1 are to google.

Any attempts at using the reference links above are obviously not working as the reference links appear to be out of scope for the top-level heading, Main, and sub-headings Subsection1 and Subsection2.

[mm-gmbd]

Just as a note of reference, VScode's built in Markdown previewer appears to take the first instance of a reference link and uses it for all references in the document:

(All links are to bing as it is the first instance of [going-on-link] in the document)

[adamaltman]

We don't support reference links. This was an intentional decision to reduce the size of our package.

[mm-gmbd]

Got it. Is there a place to document something like this? Maybe this issue is good enough, just curious as I'd be fine adding something to a "known limitations" or "unsupported features" section and opening a PR.

Thanks!

[adamaltman]

Yes! Great idea.

I hope we get accepted to GSOD: https://redoc.ly/gsod/

If so, I hope the writer(s) choose improving Redoc's docs... I'll add a label so it's findable.