Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Internal link refactor to be more resilient across different markdown renderers #3128

Closed
wants to merge 1 commit into from

Conversation

SethAngell
Copy link

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 Object being 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

Fixed internal links in 3.1.1 spec to better function in different markdown environments
@kexoth
Copy link

kexoth commented Feb 13, 2023

FYI today also needed the specification, whilst reading noticed that the section links are broken & updated them: #3160
That said noticed now that my PR is a duplicate of Yours, will mark it as such.

@handrews
Copy link
Member

handrews commented Mar 1, 2023

@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 versions/3.0.4.md on the v3.0.4-dev branch (as it seems to apply there as well), that would be fantastic. However you arrange it among yourselves :-) Or perhaps wait and see if this approach gets approved and then apply it to 3.0.4.

@SethAngell
Copy link
Author

@handrews Apologies, just now seeing your comments. Best to keep this target at 3.1 or switch it to 3.0.4?

@handrews
Copy link
Member

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants