=== Side Matter ===
Contributors: setzer
Tags: footnote, footnotes, endnote, endnotes, sidenote, sidenotes, annotation, annotations, citation, citations, shortcode, widget
Requires at least: 3.0
Tested up to: 3.6
Stable tag: 0.9
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html

Turns your footnotes into sidenotes, magically positioning each note in the sidebar next to its corresponding reference in the text.

== Description ==

Side Matter turns your footnotes into sidenotes, magically aligning each note in the sidebar next to its corresponding reference in the text. The plugin's easy-to-use shortcode and widget make it a lightweight, visually elegant tool for annotating your posts and pages.

Like margin notes in a printed text, sidenotes are well-suited for citations, digressions, cross-references, and commentary. The visual effect is similar to that used for annotations by Grantland and other websites.

Side Matter includes an options menu for toggling settings, as well as a set of built-in classes for [styling with CSS](http://wordpress.org/extend/plugins/side-matter/other_notes/). It works well with many popular base themes, including Twenty Twelve, Twenty Ten, Responsive, and Toolbox.

To use, place the Side Matter widget in your sidebar, then enclose sidenote text in a page or post using the `[ref]` shortcode, like so:

> Here's the text to annotate.`[ref]`Note text goes here.`[/ref]`

== Installation ==

1. Upload the directory `side-matter` to `wp-content/plugins`.
2. Activate Side Matter using the Plugins menu.
3. Using the Widgets menu, place the Side Matter widget in your sidebar.
4. You may now use the `[ref]` shortcode to generate sidenotes in posts and pages, like so:

> Here's the text to annotate.`[ref]`Note text goes here.`[/ref]`

To modify the plugin's default settings, use the options menu located on your Reading Settings screen.

If you'd like to customize the appearance of Side Matter notes and references using CSS, consult [Styling Side Matter with CSS](http://wordpress.org/extend/plugins/side-matter/other_notes/).

== Frequently Asked Questions ==

= Where is Side Matter's options menu? =

The options menu can be found on your Reading Settings screen.

= Does Side Matter work with responsive layouts? =

Yes. The plugin includes an option, turned off by default, to enable sidenote re-positioning upon resize/zoom in responsive themes. Enable this feature using the Responsive Positioning control in Side Matter's options menu. (It's best to leave this feature disabled if your theme is not responsive.)

= My notes just sit at the top of the sidebar. =

Your theme may not be linking `side-matter.js`, the script that aligns Side Matter notes. Check the page source to see if `side-matter.js` has been linked; if not, the problem may lie with your theme. In order to properly enqueue the script and other Side Matter assets, theme templates must include calls to [`wp_head`](http://codex.wordpress.org/Function_Reference/wp_head) and [`wp_footer`](http://codex.wordpress.org/Function_Reference/wp_footer).

= My notes appear at a regular vertical offset from their proper position. =

Some themes idiosyncratically display notes at an offset from their corresponding references in the text. Side Matter's options menu, on the Reading Settings screen, includes a field for arbitrarily adjusting your notes' vertical position.

= Why doesn't the plugin work with some themes? =

Not all themes are built to support the grafting-on of a substantial layout component like Side Matter. While the plugin works well with most base themes featuring a sidebar (including Twenty Twelve, Twenty Ten, Responsive, and Toolbox), it isn't guaranteed to display notes perfectly within all layouts. In many cases, a little tinkering with note offset or CSS will fix the problem. If you have ongoing questions about implementing sidenotes within a particular theme, though, your best resource may be the theme author.

= Can sidenotes be displayed without using the widget? =

Yes. Use the custom action `side_matter_list_notes` in your sidebar template:

    <?php
    do_action( 'side_matter_list_notes' );
    ?>

This action generates a list of Side Matter notes without wrapping them in the widget `div`. If incorporating Side Matter into a custom theme, note that your templates must include calls to [`wp_head`](http://codex.wordpress.org/Function_Reference/wp_head) and [`wp_footer`](http://codex.wordpress.org/Function_Reference/wp_footer) to properly enable the plugin.

== Screenshots ==

1. Side Matter captures footnote text using the [ref] shortcode, then magically positions each footnote alongside its corresponding reference in the text.

2. Modify default settings using Side Matter's options menu on the Reading Settings screen.

== Changelog ==

= 0.9 =
* Added a preview field to the options menu.
* Added an option to display reference figures in alphabet and Roman numeral formats.
* Added an option to set inline colors for Side Matter elements.
* Reference numeral link tags have been given a `title` attribute for accessibility.
* Removed deprecated element classes `side-matter-ol` and `side-matter-li`. Numbered classes, e.g. `side-matter-sup-6`, are now deprecated.
* Responsive positioning and fade effects are now turned off by default.
* Side Matter's options menu is now linked from its entry on the Installed Plugins screen.

= 0.8 =
* Added an option to display sidenotes on selected page types.
* Plugin documentation now includes a guide to [styling Side Matter elements with CSS](http://wordpress.org/extend/plugins/side-matter/other_notes/).
* Reduced specificity for CSS defaults in `side-matter.css`, allowing them to be more easily superseded by user CSS.
* Removed the `a` anchor elements within sidenotes to correct a stubborn layout issue. Reference numerals now link to sidenotes via `li id`.
* Side Matter now erases its options field from the database upon deletion.
* Widget admin panel now links to plugin options menu on the Reading Settings screen.

= 0.7 =
* Added an options menu to the Reading Settings screen.
* Made various tweaks for security, performance, and cross-browser compatibility.
* Paragraphs within sidenotes are now properly wrapped in `p` tags by WordPress.
* Replaced sidenote `span` tags with `div` tags to correct a display problem in some browsers.
* Sidenotes now employ jQuery fade effects for smoother transitions upon window load, resize, and zoom.

= 0.6 =
* Expanded plugin documentation.
* Rewrote `side-matter.php`, simplifying and consolidating code for future development.
* Sidenote numerals can now be styled separately from sidenote text.
* Streamlined CSS classes and jQuery selectors.
* Widget markup now better follows WordPress convention.

= 0.5 =
* Fixed a class instantiation error that was preventing plugin activation for some users.

= 0.4 =
* Initial release.

== Upgrade Notice ==

= 0.9 =
This update adds a number of features, including alternate numeral formats and a color picker for Side Matter elements. Users who have modified `side-matter.css` are advised to make a backup copy before updating.

= 0.8 =
This update includes several fixes and additions, including the option to select which page types display sidenotes. Users who have modified `side-matter.css` are advised to make a backup copy before updating.

= 0.7 =
This update adds several features, including an options menu and transition-smoothing effects. Users who have modified their copy of `side-matter.css` are advised to make a backup copy before updating.

= 0.6 =
This update includes a number of tweaks and fixes, including improved classes for CSS and separate styling for sidenote numerals. Users who have customized their copy of `side-matter.css` are advised to make a backup copy before downloading.

= 0.5 =
This update fixes an error that was preventing plugin activation for some users. Recommended.

== Styling Side Matter with CSS ==

As of version 0.9, Side Matter's options menu includes a color picker for rendering notes and figures in custom colors. Altering the appearance of Side Matter elements beyond this requires some tinkering with Cascading Style Sheets (CSS). This guide assumes some basic familiarity with CSS; beginning users may wish to start with a [CSS tutorial](http://www.htmldog.com/guides/css/beginner/).

 The easiest way to add custom styles to your site is to use a plugin that houses your custom CSS in the WordPress database, preserving it even when Side Matter (or your theme) is updated. [Jetpack Custom CSS](http://wordpress.org/extend/plugins/jetpack/) is a good example.

Side Matter comes with a set of built-in classes that make it easy to customize the appearance of sidenote and reference elements using [class selectors](http://www.htmldog.com/guides/css/intermediate/classid/). For example, all Side Matter elements may be styled at once using the class `side-matter`. The following rule will instruct browsers to render all Side Matter content (reference numerals, sidenote numerals, and sidenote text) in blue:

    .side-matter {
        color: blue;
    }

Notes and references may be styled with greater precision using element-specific class selectors. The following rules will render reference and list numerals in red while leaving sidenote text black:

    a.side-matter-ref, ol.side-matter-list {
        color: red;
    }
    
    div.side-matter-text {
        color: black;
    }

In some cases, your custom CSS may fail to take effect because the theme CSS carries greater [specificity](http://www.htmldog.com/guides/css/intermediate/specificity/). There are ways around this. For example, if you can't modify the color of superscript reference links because your theme's rules have greater specificity, try overriding the theme stylesheet via nesting or an ID selector:

    .entry-content > p > a.side-matter.side-matter-ref {
        color: red;
    }

    a[id^='ref-'].side-matter-ref {
        color: red;
    }

The `!important` declaration should be used only in rare cases, but may resolve a stubborn CSS conflict where other methods have failed:

    a.side-matter-ref {
        color: red !important;
    }

A full list of included class and ID selectors may be found below.

= Default CSS =
Note that inline color styles set in the Side Matter options menu will generally override any style rules you set in a custom CSS plugin or elsewhere. If modifying an element's `color` property with CSS, make sure to first disable custom colors in the options menu.

Side Matter also sets a few rules by default in the stylesheet `side-matter.css`. These may be readily superseded by your theme stylesheet or custom CSS.

    a.side-matter-ref:link,
    a.side-matter-ref:visited,
    a.side-matter-ref:hover,
    a.side-matter-ref:active {
        text-decoration: none;
    }
    
    sup.side-matter-sup {
        position: relative;
        top: -0.5em;
        vertical-align: baseline;
        font-size: 0.75em;
        line-height: 0;
    }

The above rules remove underlines from reference links (`text-decoration: none`) and specify a consistent, cross-theme appearance for superscript figures.

= List of Class Selectors =
Here is a complete list of Side Matter element class selectors and their uses:

* `a.side-matter-ref` selects the `a` link tags that enclose in-text reference numerals. Use this class to modify the links' colors, underline, etc. Target a specific reference link using its ID selector (e.g. `#ref-5`).
* `sup.side-matter-sup` selects the `sup` (superscript) tags that enclose in-text reference numerals. Use this class to modify the numeral figures' typographic properties, such as size, offset, and typeface.
* `div.side-matter-widget` selects the `div` element that encloses the Side Matter widget.
* `ol.side-matter-list` selects the `ol` (ordered list) element that encloses notes in the sidebar, including note numeral figures.
* `li.side-matter-note` selects individual sidenote `li` (list item) elements. Target a specific note using the note's ID selector (e.g. `#note-6`).
* `div.side-matter-text` selects the `div` elements that enclose sidenote text, but not sidenote list numerals. Use this to style sidenote text separately from sidenote numerals.
* WordPress further wraps each note paragraph in a `p` tag. Because they are generated outside Side Matter, these `p` elements cannot be selected directly using the `side-matter` class. Instead, target them using a [child selector](http://www.htmldog.com/guides/css/advanced/selectors/), e.g. `div.side-matter-text > p`.