Side Notes and Margin Notes in Tufte CSS: a WordPress Shortcode

Simplified Authoring for Tufte CSS

Our sister site Mercury Photo Bureau uses side notes and margin notes in the style of Edward Tufte. The notes are styled using a bespoke adaptation of Tufte CSS. Because the code to display the notes accessibly is quite complicated, we use a shortcode to simplify authoring.

Screen shot of a side note.

You’ll need to apply custom styles to the output. For that purpose, we’ve included plenty of CSS classes you can hook into. Refer to Tufte CSS for guidance.

Screen shot of a margin note.

For an explanation of how shortcodes work, see the WordPress Shortcode API. You should have a basic knowledge of PHP before attempting to implement this code.

Never trust user input. Unless you are personally the authoring all of the posts on your site, you must sanitize the $content, e.g., $content = sanitize_text_field( $content );. Note that this will strip all user input HTML tags on output, e.g., <span> will become &lt;span&gt.

Dependencies

Styling requires Tufte CSS or your own custom adaptation of it.

Because the output for margin notes includes the Fontawesome sticky note glyph, you’ll need to install Fontawesome via their JavaScript and SVG method. If you don’t already use Fontawesome on your WordPress site, the easiest way to implement it is to install their official plugin and change the settings to render glyphs via SVG (the default behavior is to render via web fonts).

We encourage advanced users to subset and self-host FontAwesome. This will greatly improve load times.

See the WordPress Theme Handbook for the correct way to reference the necessary scripts and styles.

If you don’t have a Pro level Font Awesome plan, you can still subset the icons by manually editing regular.js and solid.js (and their minified equivalents). Just delete the SVG definitions for all glyphs except for far-sticky-note and fas-sticky-note.

As an alternative to Fontawesome, you can substitute your own custom SVG. Just update the code below in the appropriate places.

Implementation

To use, drop the code into your theme’s functions.php or your custom plugin.

function my_mn_func( $atts, $content = null ) {
  $a = shortcode_atts(
    array(
      'id' => '',
    ),
    $atts
  );

  $id = sanitize_text_field( $atts['id'] );
  // Uncomment next line for security.
  /* $content = sanitize_text_field( $content ); */
  $content = do_shortcode( $content );

  // If you don’t want to use the Fontawesome sticky note glyph, replace the contents of the <span> with your own custom SVG.
    return '<label for="' . esc_attr( $a['id'] ) . '" class="note__toggle" alt="note"><span class="fa-layers fa-fw mn-"><i class="fas fa-sticky-note""></i><i class="far fa-sticky-note""></i></span></label>
    <input type="checkbox" id="' . esc_attr( $a['id'] ) . '" class="note__toggle" aria-role="note" />
    <small class="note note__margin" aria-role="note">
      <span class="h-screen-reader-text"> [Sidenote: </span>' . $content . '<span class="h-screen-reader-text">] </span>
    </small>';
}

add_shortcode( 'mn-', 'my_mn_func' );

function my_sn_func( $atts, $content = null ) {
  $a = shortcode_atts(
    array(
    'id' => '',
    ),
  $atts
);

$id = sanitize_text_field( $atts['id'] );
// Uncomment next line for security.
// $content = sanitize_text_field( $content );
$content = do_shortcode( $content );

return '<label for="' . esc_attr( $a['id'] ) . '" class="note__toggle note__number" alt="note"></label>
<input type="checkbox" id="' . esc_attr( $a['id'] ) . '" class="note__toggle" aria-role="note" />
<small class="note note__side" aria-role="note">
  <span class="h-screen-reader-text"> [Sidenote: </span>' . $content . '<span class="h-screen-reader-text">] </span>
</small>';
}

add_shortcode( 'sn-', 'my_sn_func' );

This will take care of rendering the shortcode, but you’ll still need to style the output. For accessibility, you should visually hide the span.h-screen-reader-text:

.h-screen-reader-text {
  clip: rect(0 0 0 0);
  clip-path: inset(50%);
  height: 1px;
  overflow: hidden;
  position: absolute;
  white-space: nowrap;
  width: 1px;
}

Please examine the original Tufte CSS to work out how to display the output in your particular WordPress theme.