=== Side Matter ===
Contributors: setzer
Tags: academic, annotate, annotation, annotations, bibliography, bibliographic, citation, citations, cite, commentary, endnote, endnotes, footnote, footnotes, margin, marginal, matter, note, notes, ref, reference, references, scholar, scholarship, shortcode, side, sidebar, sidenote, sidenotes, widget
Requires at least: 3.0
Tested up to: 3.6
Stable tag: 1.2
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html

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

== Description ==

Side Matter turns footnotes into sidenotes, magically aligning each note in the sidebar next to its corresponding reference in the text. Easily add citations, digressions, or editorial remarks to pages and posts with a simple shortcode and widget. Scholars, editors, and writers of all kinds will find the plugin of particular use.

Sidenotes have been used in printed texts for centuries, and are equally well suited to the Web. Unlike hyperlinked footnotes or endnotes, sidenotes do not require a jump down the page to pursue each reference; instead, they perch humbly and accessibly beside the lines to which they refer.

Side Matter includes an options menu as well as a set of built-in classes for [styling with CSS](http://wordpress.org/extend/plugins/side-matter/other_notes/). 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 screen.
3. Place the Side Matter widget in your sidebar using the Widgets screen.
4. Use the `[ref]` shortcode to generate sidenotes in posts and pages, like so: `[ref]Note text goes here.[/ref]`

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

For information on specifying the appearance of Side Matter elements using custom CSS, consult [Other Notes](http://wordpress.org/extend/plugins/side-matter/other_notes/).

== Frequently Asked Questions ==

= Where is Side Matter's options menu? =

You can find the options menu on your Reading Settings screen.

= My notes don't appear. =

Some themes are one-column by design and do not include a sidebar. Without a sidebar, Side Matter has no place to generate your notes. Make sure that your theme includes a sidebar and that you've placed the Side Matter widget within this sidebar.

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

This most commonly occurs when your theme has not loaded `side-matter/js/side-matter.js`, the script that aligns sidenotes. Check the page source to make sure that `side-matter.js` has been linked. (If you're developing a custom theme, 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 load plugin assets.)

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

Some themes idiosyncratically display notes at an offset from their corresponding references in the text. As a workaround for this problem, Side Matter's options menu includes a field for arbitrarily adjusting your notes' vertical offset.

= Some numeral figures don't display properly in my browser. =

Browser support for the CSS `armenian`, `georgian`, `lower-greek`, `hebrew`, `hiragana`, and `katakana` list styles is not universal. (See the [`list-style-type` documentation on Web Platform Docs](http://docs.webplatform.org/wiki/css/properties/list-style-type#Compatibility_notes) for more information.) Use Decimal, Latin, or Roman figures if this becomes a problem.

= Why doesn't the plugin work with my theme? =

Not all layouts are built to incorporate a component like Side Matter. The plugin works well with most base themes that include a conventional sidebar, but it isn't guaranteed to display notes perfectly on all sites. A little tinkering with note offset or CSS will fix most problems; in other cases, it's best to consult your theme's developer.

= Does Side Matter work with responsive layouts? =

Side Matter includes an option, turned off by default, to responsively re-position sidenotes upon browser resize or zoom. Enable this function using the Responsive Positioning control in Side Matter's options menu.

= Can sidenotes be displayed without using the widget? =

Yes. Use the custom action `side_matter_list_notes` in your sidebar template, as seen below:

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

== Screenshots ==

1. Side Matter extracts note text with a shortcode, then magically places each note in the sidebar beside its corresponding reference in the text.

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

== Changelog ==

= 1.2 =
* Added a `[ref]` quicktag button to the post editor.
* Fixed some odd behavior within the sidenote-positioning loop.
* Fixed two options menu UI bugs from the previous update.
* Sanitization of reference figures' `title` attribute has been improved.
* Using multiple instances of the Side Matter widget no longer causes `id` conflicts between notes.

= 1.1 =
* Added support for Hiragana and Katakana figure sets.
* Added localization domain path to plugin header and appended translation notes to some otherwise cryptic strings.
* Made various minor fixes to improve appearance and performance.

= 1.0 =
* Added support for Armenian, Georgian, Greek, and Hebrew numeral formats, as well as the option to hide numeral figures entirely.
* Fixed two IE-specific bugs related to proper display of `title` attributes and list numerals.
* Made various minor adjustments and fixes for appearance and performance.
* Numbered classes have been removed.
* Plugin is now localization-ready.

= 0.9 =
* Added a preview field to the options menu.
* Added an option to display reference figures in Latin alphabet and Roman numeral formats.
* Added an option to set inline colors for Side Matter elements.
* Reference numeral `a` 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 to spare inexperienced users the script load.
* 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.

== Styling Side Matter with CSS ==

Side Matter's options menu allows you to render notes and figures in custom colors by way of the Iris color picker. Changing other aspects of Side Matter elements' appearance, such as indentation or line height, requires some tinkering with CSS. (This guide assumes some familiarity with CSS; if you're a beginner, consider first reading a [tutorial](http://www.htmldog.com/guides/css/beginner/).)

 The simplest way to add custom CSS to your site is to employ a custom CSS plugin, which will preserve your changes even if Side Matter or your theme is updated. [Simple Custom CSS](http://wordpress.org/plugins/simple-custom-css/) or the [Jetpack](http://wordpress.org/extend/plugins/jetpack/) CSS module are some good examples.

Side Matter comes with a set of built-in classes that make it easy to change the appearance of sidenote and reference elements using [class selectors](http://www.htmldog.com/guides/css/intermediate/classid/). All Side Matter elements can be styled at once using the class `side-matter`. The following rule will render reference numerals and sidenotes in blue 12-pixel serif type:

    .side-matter {
        color: blue;
        font-family: serif;
        font-size: 12px;
    }

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

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

In some cases, your 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, such as overriding the theme stylesheet's specificity via nesting:

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

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

* `a.side-matter-ref` selects the link tags that enclose in-text reference numerals. Use this class to modify the links' colors, underline, etc.
* `sup.side-matter-sup` selects the `sup` (superscript) tags that enclose in-text reference numerals. Use this class to modify the numerals' typographic properties, such as size, offset, and font.
* `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.
* `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.

Note that while WordPress further wraps each note paragraph in a tag of its own, these `p` elements cannot be selected directly using the `side-matter` class. Instead, select them indirectly: `div.side-matter-text > p`.

= Default CSS =
Side Matter sets a few basic rules by default in the included stylesheet `side-matter/css/side-matter.css`. These rules will generally defer to your theme or custom stylesheets.

The first rule removes underlines from reference numeral links:

    a.side-matter-ref:link,
    a.side-matter-ref:visited,
    a.side-matter-ref:hover,
    a.side-matter-ref:active {
        text-decoration: none;
    }

The second rule specifies a consistent cross-theme appearance for superscript figures:
    
    sup.side-matter-sup {
        position: relative;
        top: -0.5em;
        vertical-align: baseline;
        font-size: 0.75em;
        line-height: 0;
    }