Use latest respec

[ralfhandl]

Fixes #3845
Fixes #3852

As discussed in TDC call on 2024-07-04

• pinned version of respec as dependency
• adjust frontmatter

As discussed in TDC call on 2024-07-11

• generate static HTML that renders faster and does not need respec-w3c.js

Differences due to new ReSpec defaults

• spacing around <h1> and <h2> - keep
• collapsible "More details about this document" was added - keep
• "Latest published version:" was added - keep
• section marker symbols (§) are now left of heading instead of right - keep

Reverted differences

• code in text had text color instead of red color
• code in code blocks had different syntax coloring

Please compare

• with new respec: https://ralfhandl.github.io/OpenAPI-Specification/oas/latest.html
• current state: https://spec.openapis.org/oas/latest.html

[handrews]

code in text now has text color instead of red color

I'm not sure I like this change. I'm trying to give it a chance, but the red text made it easier to scan for certain things.

code in code blocks has different syntax coloring

What are the differences? Is it a different package, a different configuration...?

[handrews]

code in text now has text color instead of red color

I'm not sure I like this change. I'm trying to give it a chance, but the red text made it easier to scan for certain things.

If the red is too dramatic for folks, we could choose another color? Even a gray that is distinctive enough to clearly stand out? We should run A11Y (accessabilty) metrics on our rendering (no matter what we do with this color).

[ralfhandl]

We should run A11Y (accessabilty) metrics on our rendering (no matter what we do with this color).

Good idea, which tool(s) would you recommend?

[ralfhandl]

What are the differences?

• Delimiters are now black instead of red - seems the new code color shines through
• Numbers are now bronze instead of turquoise

Both respec-rendered variants differ from Github markdown rendering.

• New: https://ralfhandl.github.io/OpenAPI-Specification/oas/latest.html#format
• Old: https://spec.openapis.org/oas/latest.html#format
• Github: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#format

[stringtheory]

We should run A11Y (accessabilty) metrics on our rendering (no matter what we do with this color).

Good idea, which tool(s) would you recommend?

Accessibility Human here :) - here is the tldr; on a11y // and an overly informative answer with more tools and info. I also did a bunch of tests for you.

tldr;

If you are just using 1 tool - use Google Lighthouse in the Chrome Developer Tools

Run a Desktop and a Mobile test | Mode: Navigation | Categories: Just check them all

It will give you some great automatic feedback and is good to check before rolling new versions.

Background

Background on Accessibility & Testing:

Regarding accessibility standards, the primary specifications you should focus on are WCAG (Web Content Accessibility Guidelines) and ARIA (Accessible Rich Internet Applications), both maintained by the W3C (World Wide Web Consortium).
It's important to note that there isn't a single, comprehensive automated test that covers the entire spectrum of accessibility compliance. Instead, achieving compliance typically involves a combination of:

• Manual testing
• Semi-automated browser extensions
• Automated tools (not necessary for your current needs)

Your Results

1. Google Lighthouse

Here are your Desktop Results (mobile were similar)

Issues:

• color contrast
• Link spacing must allow for 48px x 48px touch target
• Links must be distinguishable without relying on color
• Links must have discernible text

2. I did additional testing using the Axe DevTools - which is a browser extension and works in a similar way to Lighthouse but the results can be easier to parse.

Issues (with better stats):

• 1175 Contrast Issues -
• 31 - Links must be distinguishable without relying on color
• 2 - Links must have discernible text
• 7 - Scrollable region must have keyboard access

3. Manual Testing - you passed all of my initial checks.

I did the top manual tests for the updated site - it scored really well:

Keyboard - There are several to test here. I just did them & you are in good shape.

• Is tab order correct
• Are elements focusable when the user tabs through
• Do you have a skip to the main content link which is only visible when tabbed through with a keyboard?

ZOOM/Magnification

• Verify if the elements are displayed nicely and are still interactable.

Screen Readers

• Tested for basic navigation.
  This is super advanced and takes practice to learn. If you are on Mac use the built-in VoiceOver, and on a PC use NVDA. I just did a brief test with Voice Over and nothing horrible stood out.

[stringtheory]

I am glad to dig into the accessibility issues further and propose some recommendations to get you up to WCAG 2.1 AA Compliance (this is the current best-practice target to aim for). That seems far, far outside the scope of this issue - but I can start a thread if someone can recommend the best place for it.

[lornajane]

Thank you @stringtheory! We would definitely like to improve our accessibility game, and you have already helped us with these pointers :) Could you create a new issue for anything we are missing (in this same repo), please? Even if we don't get all of it sorted out before this round of patches, we will keep iterating.

[ralfhandl]

Created issue #3946 to tackle this.

@stringtheory Please feel free to comment and add more recommendations.

[ralfhandl]

Feedback:

• keep new default spacing
• keep new frontmatter
• use (only) static versions

[romanblanco]

Editor configuration was removed out of the changes 👍