Notes ___ and references ^

Notes are text snippets with auxiliary information such as an explanation, an editor’s comment, the source for a statement or a legally required clarification. They are typically displayed in a smaller font size than the main text.

Notes in books are traditionally called footnotes when placed at the bottom of a page and endnotes when placed at the end of a work. This distinction is blurred on the world wide web where a page can be arbitrarily long.

Notes are usually referenced from the main text with superscript numbers, letters or other symbols. Consider to use an inline note instead, if you want a short note to be placed inside the main text flow.

How to

Notes are marked by three consecutive underscores ___ after a blank line. The notes consist of the single block immediately below the three underscores, that is without another blank line in between. The block could be a simple paragraph of text, but it is common to use a numbered list whose numbers are marked as targets so that they can be easily referenced from elsewhere in the page.

A reference to a note is marked by a circumflex ^ directly followed by the text of a target that is located inside the notes. For instance, ^1 is a reference to the target #1. There can be multiple references to the same target.

Reference and target may use different string markup without impeding the link. So ^[1] would lead to the target #1 despite the brackets in the reference that are not present in the target.

Examples

The first example shows a very simple note. It does not even contain a target that could be referenced from above:

___
All rights reserved.

All rights reserved.

The longer second example starts with two paragraphs which contain references to footnotes. The footnotes are organized as a list with numbers marked as targets here.

Some authors put references in brackets.^1

You do not have to use notes markup for everything that may be called "note" in English.^2 A simple paragraph could suffice. An expandable section or subsection is often fine, too.

___
#1. Wrapping a reference in square brackets increases its width. This makes hitting it with a click or tap on the touch screen easier.^[3]
#2. Aneamal’s notes markup is primarily meant for footnotes/endnotes.
#3. See?

Some authors put references in brackets.1

You do not have to use notes markup for everything that may be called note in English.2 A simple paragraph could suffice. An expandable section or subsection is often fine, too.

  1. Wrapping a reference in square brackets increases its width. This makes hitting it with a click or tap on the touch screen easier.[3]
  2. Aneamal’s notes markup is primarily meant for footnotes/endnotes.
  3. See?

For developers

A notes block is wrapped in an HTML div element with a note role when Aneamal is translated into a webpage. The first child of the div is an HTML hr element. So the first example becomes:

<div role='note'>
<hr>
<p>All rights reserved.</p>
</div>

References are translated to HTML a elements inside sup elements. Here is the full HTML code that corresponds to the second example:

<p>Some authors put references in brackets.<sup><a href='#1'>1</a></sup></p>
<p>You do not have to use notes markup for everything that may be called <q>note</q> in English.<sup><a href='#2'>2</a></sup> A simple paragraph could suffice. An expandable section or subsection is often fine, too.</p>
<div role='note'>
<hr>
<ol type='1'>
<li id='1' value='1'>Wrapping a reference in square brackets increases its width. This makes hitting it with a click or tap on the touch screen easier.<sup><a href='#3'>[3]</a></sup></li>
<li id='2' value='2'>Aneamal’s notes markup is primarily meant for footnotes/endnotes.</li>
<li id='3' value='3'>See?</li>
</ol>
</div>

You can use CSS to style notes of course. The following stylesheet causes notes to be printed smaller than the main text and list items within notes to be displayed with a yellowish background when a user navigated to them by clicking on a reference.

[role=note] {
	font-size: smaller;
}
[role=note] li {
	padding: 0 5px;
}
[role=note] li:target {
	background: lemonchiffon;
}