SVG guide

Rationale

The preferred format for diagrams in Pan Docs is SVG.

• ASCII, Unicode, or text-only diagrams are not accessible (screen readers, etc.)
• "Raster" images do not scale, and e.g. text within them cannot be selected.
• Additionally, raster images may be troublesome to post-edit without extra "source" files (e.g. XCF or PSD files).
• Lastly, SVGs can be dynamically styled, allowing for better integration within the page.

SVG creation guidelines

SVGs can be created using a lot of programs: Inkscape, a text editor (SVGs are just XML documents!), and others.

Be wary of "image to SVG converters", as these tend to just embed the raster image within a SVG document, which most of the time generates a larger file with none of the benefits expected from a SVG.

"Raster" images, like PNG, JPEG, BMP, and so on, store pixels. SVGs (and more generally, "vector" graphics) instead contain commands to draw shapes. For this reason, and because computers are bad at recognizing shapes, converting from the former to the latter has to be largely done by hand from scratch. (On the other hand, it's a good time to go over any improvements that can be brought to the diagram!)

Dynamically-styled SVGs

A good reference is this commit. (NB: only the new SVG file and the modification to src/pixel_fifo.md need to be considered. The rest is cleanup and plumbing.) It may be a good idea to check out that example if you aren't sure and want to check something.

SVGs can be displayed in a page in two ways: either linked to from an <img> tag, or embedded directly in the HTML document via a <svg> tag. Due to technicalities, SVGs cannot access the parent document's style sheet when displayed using the former method.

The way themes change styling is using CSS variables, specifically all of these. The variables can be reused within a SVG's stylesheet to make it automatically update its style when a new theme is selected, but this requires embedding the SVG within the page for it to have access to those variables.

How-to

In theory, pasting the SVG directly within the Markdown document would work. However, this increases its size a lot, and thus hinders navigation; it also makes the SVG impossible to view and edit on its own. For these reasons, use of mdBook's "include" mechanism is preferred.

First, create the SVG file itself; see further above for general directions. To have the SVG be dynamically styled, you will likely have to open it in a text editor and manually change it. Locate the <defs> element directly within the <svg> tag, and then the <style> tag within that. Create those as necessary if they aren't present.

Now, add CSS rules to style the elements (although CSS within SVGs affects different attributes, so some attributes have different names). You can add classes and/or IDs to the elements as normal, and use those in CSS selectors.

Once that is done, you must ensure that the file contains no empty lines (whitespace doesn't count) after the opening <svg> tag. Any blank lines will break the Markdown markup, and likely yield a broken image. Additionally, remember which line the opening <svg> tag is on for the next step.

Then, add a directive to embed the file's contents, for example {{#include imgs/ppu_modes_timing.svg:2:}}. Replace imgs/ppu_modes_timing.svg with the path to the SVG from the src/ folder, and 2 with the line number the opening <svg> tag is on.

A word of caution about the directive's placement: if it is surrounded by empty lines, the image will be outside of any paragraphs, within the document's main flow. However, if it is adjacent to a line of text, it may be placed within the paragraph, which is likely not what you want.