search

OAI / OpenAPI-Specification

The OpenAPI Specification Repository
https://openapis.org
Apache License 2.0
28.4k stars 9.04k forks source link

Correctly handle appendicies in md2html #3810

Closed handrews closed 1 week ago

handrews commented 2 weeks ago

We have an Appendix A that was getting treated as a numbered section, with a second Appendix A generated for references.

This now correctly detects sections with "Appendix" in the name, and assigns letters appropriately. The generated references section is now Appendix B (and will always be the last appendix).

ralfhandl commented 2 weeks ago

Nice!

This results in

image

which is almost what I'd expect: can we snip away the Appendix A:?

handrews commented 2 weeks ago

@ralfhandl let me see if I can figure out enough JavaScript for that 😅

handrews commented 2 weeks ago

@ralfhandl it looks a bit weird to me without the "Appendix" because then the word "Appendix" doesn't appear anywhere.

oas-appendix

Ideally we would keep "Appendix A: " in the main text and leave it out of the TOC- that is what IETF RFCs do. But I don't know how to make that happen and don't have more time to spend on this. If you feel strongly about taking it out we can just go with bare letters, but out of the two not-great options I'd rather leave the redundancy in (it's not worse than what we current have) and hope someone can figure out a better solution later.

lornajane commented 1 week ago

I'm sorry, I'm confused about how to preview the changes. I don't see Appendix B at all but I know we do some extra rendering. Am I just missing the docs on this?

handrews commented 1 week ago

@lornajane

Am I just missing the docs on this?

Bold of you to assume we have docs! 🤪

I was lazy and did not publish a rendering, as you have to bounce between different branches to do it (at least until #3717 is fixed) but i should have. Here are three relevant samples (edit the URLs in the obvious ways to see other versions if you want):