OpenAPI-Specification icon indicating copy to clipboard operation
OpenAPI-Specification copied to clipboard

Preserve section links in ReSpec output

Open ralfhandl opened this issue 1 year ago • 1 comments

Direct links to RFC sections are useful, for example in https://github.com/OAI/OpenAPI-Specification/blob/3f2e047df0df5e264374a2a1aa6586a3d899ceed/versions/3.1.0.md?plain=1#L1056-L1059.

Unfortunately these currently get lost when running the Markdown sources through ReSpec and result in unspecific #bib-RFC6570 links, see for example https://spec.openapis.org/oas/latest.html#style-values.

A possible solution could be to adapt the md2html processing in https://github.com/OAI/OpenAPI-Specification/blob/3f2e047df0df5e264374a2a1aa6586a3d899ceed/scripts/md2html/md2html.js#L257-L262 and produce something like

[[RFC6570]] [section 3.2.7](https://tools.ietf.org/html/rfc6570#section-3.2.7)

that is both a bib-link and a direct link to the relevant RFC section.

ralfhandl avatar May 28 '24 15:05 ralfhandl

@Bellangelo this dovetails with other things you have been tackling.

handrews avatar May 28 '24 18:05 handrews

See https://github.com/OAI/Arazzo-Specification/pull/199 for how I addressed this for Arazzo. LMK if you'd like a similar PR here.

frankkilcommins avatar Jul 08 '24 16:07 frankkilcommins