Internal link refactor to be more resilient across different markdown renderers#3128
Internal link refactor to be more resilient across different markdown renderers#3128SethAngell wants to merge 1 commit intoOAI:v3.1.1-devfrom
Conversation
Fixed internal links in 3.1.1 spec to better function in different markdown environments
|
FYI today also needed the specification, whilst reading noticed that the section links are broken & updated them: #3160 |
|
@kexoth @SethAngell I did not see this when I made the comment just now on @kexoth 's PR. If y'all could also target this fix to |
|
@handrews Apologies, just now seeing your comments. Best to keep this target at 3.1 or switch it to 3.0.4? |
|
The link fixes have been consolidated for all versions in PR #3408 (and follow-up PRs as noted in its description), so I am closing all other link fix PRs in favor of that one. |
Hello!
While working on an OpenAPI spec for the first time the other day, I noticed that internal links on github didn't seem to be working. Upon closer inspection, I noticed that the links were trying to reference an anchor tag within the header which used a camelCase convention as opposed to a snake-case one. I believe when Github renders markdown, it removes these explicit anchor tags and instead uses the traditional snake-case ones which are generated by markdown.
For example, rather than the line
#### <a name="parameterObject"></a> Parameter Objectbeing rendered as<h4 id="parameterObject">Parameter Object</h4>, it was instead rendered as<h4 id="parameter-object">Parameter Object</h4>.To rectify this, I replaced all of the old camelCase references with snake-case versions. However, I didn't want to disrupt any downstream workflows which utilized this
<a>tag, so I also converted that value found there from camelCase to snake-case. I believe this should improve the viewing experience on Github while not breaking anything downstream.I'd love to hear opinions on this solution, or if it is even one y'all are interested in!
Thanks