blog: Semantic Sidenotes: Initial Release

I'm happy to announce the first release of Semantic Sidenotes, version 0.1. It's buggy, has an ugly interface and isn't well documented. It's also the first thing I have actually packaged up and released. Have a forgiving heart and enjoy.

What is it?

The intended user is the programmer/author (we seem to be in no short supply...). At some point it may be appropriate for inclusion in blog software, but at this point it's largely homebrew. Expect to get down and dirty with JavaScript to get it to work. ### How was it Built? Semantic Sidenotes was built from a few things. First, it's a reimplementation of the [Arc90 Unobtrusive Sidenotes](http://lab.arc90.com/2006/05/unobtrusive_sidenotes.php). I started out by using their code, and although it contains no more of their code, the design and implementation was strongly influenced by it. I've been using their library for a few months, and it's superbly put together. Kudos to them, I never could have gotten this done without their code. #### Designed to be Gracefully Degrading, Semantic However, in their sidenotes, the content of the note is stored in the title attribute of your span. While this is a clever place to put it, it doesn't allow for a non-JavaScript fallback. Nor does it allow the author to create footnotes that can become sidenotes, as I wanted to do. Semantic Sidenotes instead allows authors to write footnotes, which can then, for supported browsers, be rendered as sidenotes. This preserves the document's semantic HTML structure while simultaneously improving the user experience and interface. #### Using JQuery Semantic Sidenotes is also a jQuery library. I'm not all that good at DOM scripting, and I greatly prefer jQuery to most other JavaScript libraries. I am using version 1\.1.3, and I keep mine updated regularly, so it should stay working with recent copies of jQuery. ### How is it used? #### Convenient Sidenotes I don't think nor write linearly. However, I do want to stay somewhat on-topic. So, when I want to go off on a tangent, I write whatever I want to in a sidenote, while keeping the main line of the content consistent. That's the reason I use footnotes (besides referencing, of course) and also why I want to use sidenotes. #### Code Samples? Sure... In this initial release, Semantic Sidenotes is pretty rigid about the structure of your code. Making the HTML structure more flexible, so that the author can write naturally and let the JavaScript worry about footnotes, is one of the things I will be working on. To use a sidenote, you need to wrap the "noted" HTML with tags that have a class of ssidenote. Then, before closing that tag, you need to put an internal anchor link to the footnote in a superscript. Somewhere else in the document (probably the end, since they're footnotes, but it's by no means a requirement) you'll want to create a div with class footnote. For non-js fallback, put an anchor link in there. Then create an inner div with class sidenote_content which contains the text of the footnote. Close all your divs, and you're all set. Here's what it looks like all put together: :::html Anywhere else in the document, put your footnote: :::html (They don't have to be next to each other or anything) :::html ### Download It is available for download [here](http://gomaa.us/files/semantic_sidenotes-0.1.js). It is licensed under the CC-by-sa 2.5. ### Miscellany #### Why use *these* Sidenotes? There are [many](http://hartshorne.ca/2005/07/27/footnotes_v_sidenotes/) [fine](http://www.web-graphics.com/mtarchive/001626.php) [contenders](http://www.brandspankingnew.net/specials/footnote_3.html) in the world of HTML sidenotes. However, none of them do what Arc90's Unobtrusive Sidenotes does: *inline* sidenotes, floating among your content. They essentially require you to set aside space for notes whether they're there or not. Semantic Sidenotes aims to imitate Arc90's behavior; the content will wrap around the sidenote content when it's present. #### What is Planned for the Future? A lot. My goal for this first release is merely to get it into a state where I can use it on my blog, because I've wanted something like this for a long time. However, in the future I'm aiming for: * Better Markdown integration[^markdown]. I hope to write an extension for [python-markdown](http://www.freewisdom.org/projects/python-markdown/) before I'm done[^done]. * More flexible, configurable structure. Ideally, you'll be able to keep your document content exactly as it is now, and use configuration options to get Semantic Sidenotes to adapt to your content, rather than the other way around. * Better documentation and a "real" release. Like, in a tarball and not just a link. Maybe even it's own URL. * Backwards compatibility with Arc90's sidenotes.