Along with the new release of PHP Markdown 1.0.2b7 comes this new
version of PHP Markdown Extra. It contains every improvements of PHP
Markdown 1.0.2b7 plus some new fixes and two new features. You can
download it here:
<http://www.michelf.com/docs/projets/php-markdown-extra-1.1b1.zip>
and you can test it on the PHP Markdown Dingus (select PHP Markdown
Extra):
<http://www.michelf.com/projects/php-markdown/dingus/>
Footnotes
---------
Footnotes have been discussed a lot on this list back in [July 2005]
[1]. A year has passed and I implemented nothing. I looked back at
that old thread recently to rediscover the syntax and finally decided
to add it to Extra.
[1]: http://six.pairlist.net/pipermail/markdown-discuss/2005-July/
thread.html#1401
How do footnotes work? Mostly like reference-style links. There is a
marker in the text which gets converted to a superscript number in
the HTML rendering. There is a definition that can happen anywhere in
the document and which is appended at the end inside a list of
footnotes. A footnote looks like this:
That's some text with a footnote.[^1]
[^1]: And that's the footnote.
Footnote definitions can be found anywhere in the document, but
footnotes will always be listed in the order they are linked to in
the text. Note that you cannot make two links to the same footnotes:
if you try the second footnote reference will be left as plain text.
Each footnote must have a distinct name. That name will be used for
linking to and from footnote references, but has no effect on the
numbering of the footnotes. Names can be anything which is valid
within an id attribute in HTML.
Footnotes can contain block-level elements, which means that you can
put multiple paragraphs, lists, blockquotes and so on in a footnote.
It works the same as for list items: just indent the following
paragraphs by four spaces in the footnote definition:
That's some text with a footnote.[^1]
[^1]: And that's the footnote.
That's the second paragraph.
If you want things to align better, you can leave the first line of
the footnote empty and put your first paragraph just below:
[^1]:
And that's the footnote.
That's the second paragraph.
### Output
It has been said countless times in the discussions that one output
format cannot satisfy everyone. So I'm not trying to make something
which will work for everyone. I decided I'd follow what I've seen on
Daring Fireball, as I think it's a pretty good default, but with some
minor differences. Here is the default output from the first sample:
<p>That's some text with a footnote.
<sup id="fnref:1"><a href="#fn:1"
rel="footnote">1</a></sup></p>
<div class="footnotes">
<hr />
<ol>
<li id="fn:1">
<p>And that's the footnote.
<a href="#fnref:1"
rev="footnote">↩</a></p>
</li>
</ol>
</div>
A little cryptic, but in a browser it will look like this (minus
links and superscript):
That's some text with a footnote.1
__________________
1. And that's the footnote. ?
The "rel" and "rev" attributes on the links express the
relation they
have with the elements they link to, the reference links to the
footnote and the backlink is a reverse reference from the footnote,
hence rel= and rev="footnote". They can be used to style the elements
with CSS rules such as:
a[rel="footnote"]
a[rev="footnote"]
So this is what PHP Markdown Extra 1.1b1 does. I'm thinking about
adding some configuration variables to allow customized class and
title attributes on the in-text reference and the backlink to make
that even more usable.
### Limitations
* You cannot make a footnote without having the content wrapped in
a paragraph
or another block-level construct. I've been wondering if it
would be good to
allow, somehow, span-level footnotes.
* It's probably not the best way to add bibliographic references when
a reference can appear many times in a document. I think a
distinct syntax,
using another special character instead of `^` would be better
suited for
that purpose.
Abbreviations
-------------
PHP Markdown Extra 1.1b1 adds supports for abbreviations (HTML
`<abbr>` tag) as an experimental feature. How it works is pretty
simple: create an abbreviation definition like this:
[HTML]*: Hyper Text Markup Language
[W3C]*: World Wide Web Consortium
then write text such as:
The HTML specification
is maintained by the W3C.
and any instance of those words in the text will become:
The <abbr title="Hyper Text Markup
Language">HTML</abbr>
is maintained by the <abbr title="World Wide Web
Consortium">W3C</abbr>.
Abbreviation are case-sensitive, and can span on multiple words when
required. An abbreviation may also have an empty definition, in which
case the title attribute will be omitted.
Operation Tigra Genesis is going well.
[Tigra Genesis]*:
Abbreviation definition can be anywhere in the document. They won't
appear in the final result other than within the text as `<abbr>`
elements.
This syntax is a work in progress. I'm not sure the syntax is
distinctive enough from standard link definition. I'm open to
suggestions.
PHP Markdown Extra 1.1b1
------------------------
* Added a syntax for footnotes.
* Added an experimental syntax to define abbreviations.
* Fixed a bug where Markdown Extra outputs invalid HTML when a
horizontal
rule isn't preceded *and* followed by a blank like.
* Fixed a bug which would cause some block-level elements to appear
inside a
a tag with markdown="span", or markdown="1" defaulting
to span
content.
Michel Fortin
michel.fortin@michelf.com
http://www.michelf.com/