raspberrypi / documentation

The official documentation for Raspberry Pi computers and microcontrollers
https://raspberrypi.com/documentation
Creative Commons Attribution Share Alike 4.0 International
5.26k stars 2.01k forks source link

Add tabs to the documentation #3838

Closed nathan-contino closed 2 months ago

nathan-contino commented 2 months ago

Uses https://github.com/asciidoctor/asciidoctor-tabs to introduce tabbed content to the docs.

Had to do some finagling to get the CSS and JS to work correctly. Then, customised the tab appearance to better fit in with our docs aesthetic.

Works well in testing. I'm going to roll out this low-risk single section update, monitor it for a week or so, and then improve additional sections of the docs as we move forward.

Bonus: because of this investigation, I also figured out how we can potentially add reproducible declarative diagrams to the docs with https://docs.asciidoctor.org/diagram-extension/latest/ (!!!). This is something the engineers have wanted for ages, and would dramatically reduce the amount of bad ascii art I'm forced to add to the docs at times. But I'll hold off on that until I'm confident that this is working well.

Before:

Screenshot 2024-09-06 at 13 20 02

After:

Screenshot 2024-09-06 at 13 19 12 Screenshot 2024-09-06 at 13 19 27 Screenshot 2024-09-06 at 13 19 32 Screenshot 2024-09-06 at 13 19 37
lurch commented 2 months ago

Nice one! :heart: Does this also work correctly on mobile-phone browsers?

nathan-contino commented 2 months ago

Does this also work correctly on mobile-phone browsers?

Indeed it does. Tested on Android in Chromium and Firefox, and on iOS in Safari with success. Gets a little cramped sometimes, but very much usable.