Skip to main content

Create Omnigraffle infographic and convert to SVG

Why this doc: to show how-we-did create SVG files to serve as infographics on the site

For who: anyone handy with clickable images and eager to contribute or update infographics

Result: semi-automaticly (re)generated SVG files in the right spot.

Three steps:

  1. Use Omnigraffle app
  2. Run node maintenance/fixOmnigraffleSvgOutput.js to fix the svg for our Docusaurus purposes. This script enhances the compatibility and display of OmniGraffle-produced SVGs.
  3. Incoperate resulting svg in a Docusaurus page

1. Omnigraffle app​

Commercial app available here: https://www.omnigroup.com/download. We've used version 7.

Sub steps

  1. Create or adjust your drawing and links in the drawing

  2. Export to svg in the right directory: [root]/static/img

  3. Set the background to transparent, tick the box in the Omnigraffle UI

  4. Save or replace file

Step 2 below expects the svg file to be in /static/img but must be run from the [root]

2. Script fixOmnigraffleSvgOutput​

In short, this script enhances the compatibility and display of OmniGraffle-produced SVGs.

Run node maintenance/fixOmnigraffleSvgOutput.js to fix the svg for our Docusaurus purposes. This script enhances the compatibility and display of OmniGraffle-produced SVGs.

Run this script from the [root] of your project, it expects your files to be in dir [root]/static/img

Brief Description​

This Node.js script is for dealing with SVG files generated by OmniGraffle in a Docusaurus project. It tackles common OmniGraffle SVG inconsistencies, corrects namespaces and linking attributes, and adjusts SVGs for flexible, responsive use by removing fixed dimensions.

The script also fixes relative URLs in anchor tags to ensure correct linking within the Docusaurus project and rearranges specific SVG elements for optimal rendering.

Detailed Description​

This Node.js script is for OmniGraffle-generated SVGs. OmniGraffle, a diagramming and digital illustration application, often uses non-standard or deprecated attributes in its SVG output, which this script addresses to improve compatibility.

The script defines replacements to rectify common OmniGraffle SVG output issues, including the removal of SVG DOCTYPE declaration and XML version tag, and correction of the 'xl:' namespace and 'xl:href' attributes to 'xmlns:xlink' and 'xlink:href' respectively.

The script reads all files in the specified directory (../static/img), and for each '.svg' file, it performs the following:

Applies the predefined replacement rules

Checks for 'viewBox' attribute on the SVG element using the 'cheerio' library, and if found, removes the 'width' and 'height' attributes for responsive scaling

For each anchor ('a') element, it corrects relative URLs and rearranges rectangle ('rect') elements within the anchor for optimal rendering

Modified SVG data is then saved back to the file. Error handling is implemented at several stages to address potential issues during directory scanning, file reading, and writing.

In essence, this script is a tool for preprocessing OmniGraffle-produced SVGs for better usability, compatibility, and display.

3. Incoperate resulting svg in a Docusaurus page​

In a markdown file that is in the build-able reach within the Docusaurus tree, e.g. under the docs directory, say for example import Scraping from '/img/scraping.svg';

where Scraping is a React object that you have to call with <scraping /> so that DS can conjure up the image on the screen behind the scenes. and scraping.svg is the updated or newly produced svg in the above-described process.

See detailed instructions here: https://docusaurus.io/docs/markdown-features/assets#inline-svgs