Create an alternative for include_svg under Redocly

[mDuo13]

Currently we use the include_svg(...) filter to embed SVG diagrams in the docs as a means of implementing theme-aware diagrams which change color to match the user's current light/dark theme setting.

Note: The published version of that page has a bug in the example syntax (it's actually parsing the include_svg syntax instead of showing it)

This tool inlines the SVG diagrams into the resulting page HTML so that they can be re-styled on the fly to match the light/dark theme of the docs. It does some pre-processing of the SVG files' contents so that they work properly when inlined in the HTML context of the document; without it, some problems occur such as all the diagrams on one page being clipped to the bounding box of the first diagram because they reuse IDs that are supposed to be unique within the document.

(Figure: showing what a diagram looks like when it gets cut off due to its clipping box using the same ID as another SVG also inlined into the same document. The include_svg() filter renames IDs to be unique so that this doesn't happen.)

We need an alternative or equivalent to work under Redocly. Options include:

• Go back to including diagrams as simple images with ![title text](/path/to/image.svg) syntax.
  • This would require redoing many of our existing diagrams (121 instances, though some of those refer to the same diagrams) so that they can be safely used in both light and dark themes (i.e. no transparent backgrounds).
  • It would also sacrifice the ability to have the diagrams be recolored to match the current theme.
• Implement a React component that can inline the SVG with some changes in the same way as the current Dactyl filter.
  • Unclear if this is possible and how best to implement this under Redocly. (Some things might need to happen at build time rather than at view time.)
• Implement a React component that can switch a diagram between two SVG files based on the current theme.
  • This would require creating additional versions of existing diagrams so that there's one for each theme.

It might be possible to come up with another approach, too, but I'm not sure.

[mDuo13]

Redocly has implemented an inline-svg component (beta docs link, requires login) which should (hopefully) solve this.

Example syntax:

{% inline-svg file="./images/logo.svg" /%}