=== Side Matter ===
Contributors: setzer
Donate link: http://christophersetzer.com/donate/
Tags: footnote, footnotes, endnote, endnotes, sidenote, sidenotes, annotation, annotations, citation, citations, shortcode, widget
Requires at least: 3.2
Tested up to: 3.5.1
Stable tag: 0.8
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 marginal notes in a printed text, sidebar notes are well-suited for digressions, cross-references, and commentary. The effect is similar to that used for annotations by Grantland and other websites.

Side Matter is responsive by default, and 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]`Sidenote 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]`Sidenote text goes here.`[/ref]`

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

For information on customizing the appearance of Side Matter notes 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 it work with responsive layouts? =

Yes. By default, the plugin will automatically re-position sidenotes to their proper places when the browser window is resized or zoomed. This function can be disabled using Side Matter's options menu on the Reading Settings screen. (Disabling responsive sidenotes is a good idea if your theme layout is not responsive; doing so will avoid unnecessary script load on browser resize.)

= My notes aren't aligned with their references in the text. =

Your theme may be failing to load `side-matter/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 templates. In order to properly enqueue the script, a theme 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. =

For one reason or another, some themes cause notes to appear at an offset from their corresponding references in the text. Side Matter's options menu (found on the Reading Settings screen) includes a field with which you can arbitrarily adjust your notes' vertical positioning.

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

WordPress themes vary widely. Some themes don't include a sidebar; others don't enqueue scripts correctly; still others are laid out in a way that conflicts with the Side Matter script. While Side Matter works well with most base themes that feature a sidebar (including Twenty Twelve, Twenty Ten, Responsive, and Toolbox), it isn't guaranteed to display notes perfectly within all themes. If you need help getting the plugin to work with a specific theme, your best resource may be the theme developer.

= How do I modify the appearance of sidenote list numerals separately from sidenote text? =

 The section [Styling Side Matter with CSS](http://wordpress.org/extend/plugins/side-matter/other_notes/) includes instructions for styling sidenote numerals and text separately. In short, styles applied to the `ol.side-matter-list` or `li.side-matter-note` element classes affect list numerals and text; styles applied to the `div.side-matter-text` tag class affect sidenote text exclusively.

= Can Side Matter notes 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' ); ?>

Additional information for theme authors may be found in the [For Theme Authors](http://wordpress.org/extend/plugins/side-matter/other_notes/) section.

== Screenshots ==

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

2. Default plugin settings may be modified using an options menu on the Reading Settings screen.

== Changelog ==

= 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.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 ==

Side Matter comes with a set of built-in classes that make it easy to customize the appearance of sidenote and reference elements using [CSS class selectors](http://www.htmldog.com/guides/css/intermediate/classid/). The included stylesheet `side-matter.css` is a handy place to start editing Side Matter's CSS, but keep in mind that WordPress will overwrite this file with a blank copy whenever the plugin is updated. (The same caveat holds for editing your theme's `style.css`.)

The best solution for this problem is to employ a plugin that houses user CSS in the WordPress database, thus preserving it when the plugin or theme is updated. The [Jetpack Custom CSS module](http://wordpress.org/extend/plugins/jetpack/) is a good example.

All Side Matter elements may be styled at once using the class `side-matter`. For example, the following CSS rule will 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 crimson while leaving sidenote text black (see [Screenshots](http://wordpress.org/extend/plugins/side-matter/screenshots/) for a similar example):

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

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

= Default CSS =
Side Matter sets a few rules by default by way of the plugin stylesheet `side-matter.css`. These may be superseded by rules you write to your own stylesheet.

    a.side-matter-ref {
        color: inherit;
        text-decoration: none;
    }

The above rule displays reference numeral links in the surrounding content's text color (`color: inherit`) and removes underlines (`text-decoration: none`).

    ol.side-matter-list {
        list-style-type: decimal !important;
    }

This rule prevents themes from interfering with the display of sidenote list numerals.

= List of Class Selectors =
Below is a full list of Side Matter class selectors and their uses.

* `a.side-matter-ref` selects the `a` link tags that enclose in-text reference numerals. Target a specific element by appending its reference number, e.g. `a.side-matter-ref-5`.
* `sup.side-matter-sup` selects the `sup` (superscript) tags that enclose in-text reference numerals. Use this class to control the format of the superscript numerals themselves. Target a specific element by appending its reference number, e.g. `sup.side-matter-sup-3`.
* `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 numerals.
* `li.side-matter-note` selects the sidenote `li` (list item) elements themselves. Target a specific note by appending `li.side-matter-note-` with the note number, e.g. `li.side-matter-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. Target the text of a specific sidenote by appending `div.side-matter-text-` with the sidenote number, e.g. `div.side-matter-text-2`.
* If a sidenote contains multiple paragraphs, WordPress will wrap the text in `p` (paragraph) tags. Because they are generated outside Side Matter, these `p` elements cannot be selected directly using the `side-matter` class. Use the [child selector](http://www.htmldog.com/guides/css/advanced/selectors/) method instead (e.g. `div.side-matter-text > p`).

== For Theme Authors ==

As an alternative to the Side Matter widget, use the custom action `side_matter_list_notes` in your sidebar template(s). This action generates a list of Side Matter notes without wrapping them in a widget `div`:

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

When adding Side Matter to a custom theme, note that your 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) to properly enable the plugin.