CSS Inline Annotations

The layout of this site is very much inspired by docco.coffee, however unlike docco it uses CSS floats instead of tables. When I started the project, I hadn't anticipated what a pain it would be to have annotations appear alongside their accompanying code without having to wrap the page up in hundreds of ugly containers and styling divs.

Through continued experimentation I did however, come up with three neat ways to achieve this layout.

Using absolute placement

This type of margin annotation is best used for small pieces of text such as page references or subscript numbers. The advantage of this method is that it's lightweight and doesn't require a great deal of thought during implementation; it's also robust and won't break. Using position:absolute on an inline element and then defining its right: or left: placement but not its top: or bottom: properties.

The disadvantage is that too much text in a single annotation or multiple annotations to a single line will overlap each other, and since absolutely positioned elements are outside the flow of the document they cannot be styled to flow around each other. This method does however work perfectly in Internet Explorer, Firefox and Chrome.

/* 10px from right border */
.annotation {
	position: absolute;
	right: -10px;
}

/* 400px from left border */
.annotation {
	position: absolute;
	left: 400px;
}
			

Using :after "hack" on floating pair

This method required me creating a pair of floats such that the left float had a set width and the right float would expand to fill the remaining space. I did this by creating a massive container element for the page and made sure to give it width:100%; overflow:hidden. Then, I set my left element to float:left and on my right element used a hack to make it fill the remaining space by giving it the overflow:hidden; property.

By using this layout, you'll see that there is an obvious problem; the first being that paragraphs will wrap into the right column if you place two of them one after another. The second problem is that you require a messy <div class="clear"> after each group of elements, which is something I really don't want to maintain on a markup level. The first problem can be fixed by using the CSS property clear and the second, by using the declaration :after.

For the main body we want it to clear other instances of itself. So, we add clear:left to its declaration. This means that it will reset the left float on the page. For the annotations we want them to clear entire blocks of text so that we can start other paragraphs after having inserted code, thus we add clear:both to its :after declaration, causing it to reset both floats.

To get an idea of the simplicity of the markup, view the source of this page which uses the same method. This method also works perfectly in Internet Explorer, Firefox and Chrome.

.container {
	width: 100%;
	overflow: hidden;
}

/* paragraph (left) */
p {
	float: left;
	width: 450px;
	clear: left;
}

/* code (right) */
pre {
	overflow: hidden;
}

pre:after {
	clear: both;
}
			

Using a container element

This method is disgusting. So disgusting. Hence, why I never used it. The markup is much longer than the other two methods, but due to how robust this method is I thought I may as well put a note down about it. This method involves creating a container for each set of annotation pairs with a float layout similar to the previous method.

The advantage of this method is that you have fine tune control over the annotation pairs, and the disadvantage is that it requires alot of markup for each instance of pairs. This method does however, work perfectly in Internet Explorer, Firefox and Chrome.

.container {
	width: 100%;
	overflow: hidden;
}

/* paragraph (left) */
p {
	float: left;
	width: 450px;
}

/* code (right) */
pre {
	overflow: hidden;
}