=== Side Matter ===
Contributors: setzer
Tags: academic, 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.1
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, and editorial remarks to pages and posts with a simple shortcode and widget. Writers, editors, and scholars will find the plugin of particular benefit.

Margin notes have been used in printed texts for centuries. They function equally well on the Web: unlike hyperlinked footnotes, sidenotes don't require jumping down the page to follow up on each reference. Instead, they perch humbly and accessibly beside the lines to which they refer.

Side Matter includes an options menu for changing default settings as well as a set of built-in classes for [styling notes and reference figures 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 the sidebar.

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

Your theme may not be loading `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.

= 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. 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 varies. (See [Web Platform Docs](http://docs.webplatform.org/wiki/css/properties/list-style-type) for more details.) Decimal, Latin, and Roman figures enjoy broader support and are unlikely to cause problems.

= 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's not 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? =

Yes. The plugin 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 sidenote text using the [ref] shortcode, then magically positions each note in the sidebar next to its corresponding reference in the text.

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

== Changelog ==

= 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 typeface, indentation, or spacing, requires some tinkering with Cascading Style Sheets (CSS). This guide assumes some familiarity with CSS; if you're a beginner, start with a [tutorial](http://www.htmldog.com/guides/css/beginner/).

 The simplest way to add custom styles to your site is to employ a separate plugin to house your custom CSS, thus preserving it when Side Matter or your theme is updated. [Simple Custom CSS](http://wordpress.org/plugins/simple-custom-css/) or the Custom CSS module included with [Jetpack](http://wordpress.org/extend/plugins/jetpack/) are good examples.

(Note that inline color styles set in the Side Matter options menu will generally supersede style rules you set elsewhere. If you're planning to use your own CSS as described here, be sure to disable custom colors in the options menu.)

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/). For example, all Side Matter elements can be styled at once using the class `side-matter`. The following rule will render all Side Matter content (reference numerals, sidenote numerals, and sidenote text) 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 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 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 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 sparingly, but may resolve a stubborn CSS conflict where other attempts have failed:

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

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

Note that WordPress further wraps each note paragraph in a `p` tag. Because they are not generated by Side Matter, these `p` elements cannot be selected directly using the `side-matter` class. Instead, select them indirectly by way of [parent elements](http://www.htmldog.com/guides/css/advanced/selectors/), e.g. `li.side-matter-note > 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`. Their low-specificity selectors mean these defaults will defer readily to rules set by your theme or any 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, cross-browser appearance for superscript figures:
    
    sup.side-matter-sup {
        position: relative;
        top: -0.5em;
        vertical-align: baseline;
        font-size: 0.75em;
        line-height: 0;
    }