Gallery Cheatsheet

Design Notes and How-To Guide for Gallery Posts


November 3, 2022

These notes accompany my templates for posting different types of visual content:

They detail commonly used processes, relevant tools, and notes on design and accessibility considerations.

This page was last compiled on November 07, 2022.

Web Design


Set values in the params: field of the YAML header.

This is an inline code chunk for conditional inclusion of text:

`r if(params$interactive){"This sketchnote is interactive. Try clicking around various parts of the image"}`

Toggle the </> code menu to see the R code chunk params-prep used to prepare variables used in text about the sketchnote.

All about the YAML

Include these values every time:

title: "Sketchnote Page"
subtitle: "for visual summaries, illustrations, etc."
category: "illustrations/visual-summaries/conceptual-maps/dataviz/misc"
date: 2022-11-01

These are used to generate text:

  drawing_tool: "notability/concepts" ## must be in _params-dict.R ##
  date_drawn: 2022-11-01
  draw_type: "illustration/sketchnote" ## pick one
  interactive: TRUE ## if SVG contains any links or interactivity
  main_alt_text: "" ## write this using the relevant alt-text strategy ##

Include only if you want to override the default values gallery/_metadata.yml:

  • just save images/objects using the correct name (featured.*, main.*)
  • add any resources embedded using HTML tags to the resources: list. If not, they won’t get copied into the output directory.
image: "images/featured.png"
image-alt: "A hand-drawn illustration/sketchnote described in this article"
  - "images/main.svg"

Specific to template posts:

    code-tools: true


  1. Export sketch from ipad to images/ipad.png or images/ipad.svg (depending on app support)
  2. Start a new Inkscape document and import the sketch.
  3. Crop the image to remove excess white space (i.e. if iPad export was A4): how-to
  4. Resize the canvas to fit: File > Document Properties > Fit Page to Selection
  5. Convert image Object to Pattern
  6. Divide image into anchor regions by adding a line (b) or shape, add the image pattern to the selection (s), and applying Path > Division (⌘/): tutorial
  7. Right click divided region and select Create anchors. Add URL to href field, and set target=_blank
  8. Inspect XML tree to check anchor nodes (optional)
  9. Save graphic to images/feature.svg

Screenshot of inkscape menu dialogues and options for adding anchor

The default snippet assumes the sketchnote/svg is named main.svg

To customise the display or caption of the sketchnote/illustration, or to display multiple SVGs, modify and include the snippet below in place of the {{< include ../../ >}} shortcode .

  • .column-page class is predefined by Quarto theme1
  • <figure> tag provides support for a <figcaption>2
  • <object> embeds the SVG, with .sketchnote class defined in styles.css specifying type="image/svg+xml" and other custom attributes
  <object data="images/main.svg" class="sketchnote"> </object>
  <figcaption style="text-align: right">Cynthia Huang © `r format(ddate, "%Y")`, [CC BY-SA 4.0](</figcaption>

Description of `r dtype`:

> `r params$main_alt_text`

`r if(params$interactive) {"Links embedded in the graphic:"}`
Including interactive SVGs

There are four ways to include SVG in Web pages:

  1. as an <img> element. This is what ![](sketchnote.svg) will render as and essentially converts the SVG into a raster image (which means no child element interactions).
  2. as a CSS background. Haven’t tried this; seems to be recommended for decorative images.
  3. Inline SVG. Also haven’t tried this; would likely preclude GUI editing of the SVG so probably only suitable for simple vector graphics (which don’t have the complicated pattern elements of sketchnotes)
  4. as an application embedded via <object> element. This preserves any links embedded inside the SVG, and supports interfacing between the parent document and the SVG object via SVG DOM (which I don’t yet understand how to use).

Reference Resources:

2022-11-02: I picked embedding via the <object> element because it was the only one where hyperlinks I inserted into the .svg using Inkspace still worked. I plan to experiment with more advanced interactivity in the future.

Web Accessibility

Notes on SVG and Sketchnote Accessibility

About SVGs and alt-text attributes:

  • SVG is not an image, it is a graphics-document (defined using XML)
  • alt-text for the sketchnote is defined in params: main_alt_text: using the strategies detailed below
  • aria-label or aria-labelledby attributes are recommended for objects.3
  • Fallback content (inside <object> tags) is only rendered when the object embedding is not successful, so is not a suitable place to put text for accessibility 4
  • including <title> and <desc> directly in the SVG is often recommended but only suitable for inline SVG.5

About sketchnote/data-viz accessibility:

  • if the SVG is interactive you can make it screen reader traversable… but it’s complicated and involves ordering and naming nodes appropriately, amongst other things. One would need to adapt these instructions for creating an Accessible Graph.
  • an option for 301 level WCAG conformance offered by Nitya Narasimhan in this discussion thread started by Megan Sullivan is turning the graphic into a “interactive information guide”

Resources List:

2022-11-02: At the moment, all alt-text is provided below the SVG figure. I don’t think this is optimal for screen-readers but embedding alt-text is complicated and beyond me right now.7 My approach will likely evolve as I learn more html/css/svg concepts.

Alt Text Strategies

Use some or all of the following elements to describe the purpose, content and “flow” of the illustration. The description can be more comprehensive compared to a sketchnote.

  • Illustration Type:
    • cartoon
    • schematic
    • illlustration
    • (line) plot
    • visual representations
  • Description of visual elements with position context:
    • On the left…
    • A row of…
    • Left panel… Right panel…
    • The progression goes from…
  • Text quotes and labels in context:
    • Text above… quotes Jenny Bryan: “Collaboration is…”
    • Text above the laptop reads: “Plan on it.”
    • several anchors, each labeled “Commit”
    • a cape that reads “code hero”…
  • Clarification of key message or takeaway
    • The point being: …
    • Main text:

Strategy and examples adapted from Allison Horst’s Stats Illustrations

Follow this recipe for image descriptions which provide context and some key details about the sketchnote. Remember the point isn’t to share every visual and text element of the sketchnote in the alt-text, but to describe the function provided by the sketchnote.

  1. Visual Context: black and white {digital/hand-drawn} visual notes
  2. Content Context: summarising {title of source media or event}
  3. Key takeaway: {key quote or note}
  4. Prominent visual element: {any signature elements for which visual description should be included}

Adapted from Sketch Note Accessibility by Saara Kamppari-Miller


  1. See Article Layout↩︎

  2. See HTML↩︎

  3. See this stackoverflow answer for example code↩︎

  4. as explained by this stackoverflow answer↩︎

  5. See Accessible SVG: Methods for Adding Alternative Content by Carie Fisher↩︎

  6. This is not a light read. It’s much further down the rabbit hole than most people (myself included) have time for.↩︎

  7. See discussion in Sketch Note Accessibility by Saara Kamppari-Miller↩︎