docsy Redoc left navigation auto scrolling and link changing on scrolling is not working anymore

We upgraded our documentation site from docsy version 0.6.0 to 0.7.1 and we are using the redoc shortcode to publish API documentation.

After the upgrade, the left navigation of redoc is not working anymore. There were no issues with docsy 0.6.0, but it is not working anymore with 0.7.1. We tested with the redoc example as shown on the docsy documentation site.

This is probably related to this redoc issue: Left navigation auto scrolling and link changing on scrolling is not working. We have tried multiple workarounds, but were unable to fix it ourselves.

Hope you can help out. Thanks.

Jul 21 '23 10:07 addie-janssen-rhdhv

Hi, I haven't tested the shortcode with Docsy 0.7. yet, I'll try to take a look at it next week. From the issue you have linked it seems that creating a layout without the left-side docsy ToC (the aside that contains the sidebar.html partial) might be a workaround.

Jul 21 '23 11:07 fekete-robert

Ok, so it seems that there are multiple open issues (for example https://github.com/Redocly/redoc/issues/2080 ) that hint at redoc 2.0.x release not playing along with Bootstrap 5. Using redoc 1.x in the shortcode (like <script src="https://rebilly.github.io/ReDoc/releases/v1.22.2/redoc.min.js"></script> ) might be a workaround, but 1.x supports only OpenAPI 2.0, and fails for OpenAPI 3.0/3.1

I'll try to think of a way to check the OpenAPI version of the file referenced in the shortcode and fallback to the older redoc version if it's OpenAPI 2.0, but unfortunately that doesn't solve the problem for OpenAPI 3.0 specs, and so far I couldn't get the mentioned workarounds working in my test environment :(

Jul 25 '23 12:07 fekete-robert

Thanks for the feedback. All our API specs are Open API 3.x. So going back (even temporarily) to an older version that is not supporting OpenAPI 3.x is not an option for us.... For now, we will downgrade Docsy to 0.6.0 again and wait for a fix.

Jul 27 '23 13:07 addie-janssen-rhdhv

I encountered the same issue. The workaround I use is to create a layout dedicated for Redoc. In the layout, I ensure Bootstrap is not included.

Mar 27 '24 17:03 huanlin

That sounds like a great solution. How do you exclude Bootstrap from that layout? Can you share your layout?

Mar 28 '24 10:03 addie-janssen-rhdhv

Hi, I have updated my note about this issue and included a demo to show how I fix it with a customized Redoc layout. For details, please refer to this post: Redoc side menu woes with Bootstrap CSS 5.x

Apr 07 '24 02:04 huanlin