Yes! Markdown needs attributes, not footnotes

I tried to post this to the Markdown mailing list, but they have a policy of rejecting (not just moderating) non-member mailings. Seems a bit harsh to me, considering that a combination of moderation and spam filtering is not really that much of a burden (as I know from copious experience), but whatevah. I really don't have room to join yet another mailing list.

In response to a thread that started out discussing internal links, and then falling back to footnotes, Arisotle Pagaltzis made this brilliant suggestion:

Lately I’ve increasingly been thinking that it would be nice, perfectly sufficient for footnotes, but also useful for many other uses, to have a {@attr=value} syntax (or something similar) which attaches the given attribute to its surrounding tag. So this example attribute {@id=foo} would be ganked from where it is and dattached to the tag for this paragraph: <p id="foo">; whereas *this {@class=shout}* would attach to the emphasis tag: <em class="shout">

I want to say to the Markdown folks: please, please listen to Aristotle's suggestion. It is exactly what Markdown needs now. It would add much of the power and flexibility that is currently lacking when I consider Markdown against reStructuredText, and it would do so without the welter of punctuation in ReST. A complete win. He also gives an example of how this would enable useful image elements for Markdown:

![{@width=200} Or image metadata.](bar.png) {@align=center}

Currently it is not possible to use Markdown syntax to produce images that meet general usability guidelines. You have to embed a full img tag. Aristotle's suggestion elegantly solves that problem as well.

I think that this is far more important than such minutiae as footnotes, which are all the current rage on the Markdown list. This is not to say that the need for footnotes is minute, but rather that the need for footnotes can easily be seen as one aspect of a more general problem in expression. If Markdown had a way of asserting ID attributes, there would be flexible support for the many different ways people want to express footnotes, margin notes, biblio refs, etc. But by solving footnotes as a complete problem in themselves, Markdown is just heading down the path to punctuation madness.

I suggest starting with flexible attribute syntax such as Aristotle suggests, using this for footnotes as far as it goes, and then, if usage experience shows that something yet more convenient is needed, reconsider specialized footnote syntax.

I also think it's worth explicitly supporting the attribute syntax at the top of a markdown document as a way to express overall document metadata, which is another gap I see in Markdown.

In his concurrence Jelks Cabaniss suggests:

The only thing I might add are "shortcuts" when the attributes are ID and CLASS: {#foo} as an alias of {@id=foo}, and {.bar} for {@class=bar}.

But I think these should be left off for the moment, and maybe added later if they seem especially useful. Again I'm just wary of increasing the amount of punctuation one has to remember. Jelks does wrap up with what I consider the knockout point:

BTW, take a look at It's sprinkled full of "real HTML" precisely because of this deficiency. (There aren't any CLASS attributes in that particular document, but even there, if there were Markdownish equivalents of ID and TITLE attributes, that would all go away.)

I'm pretty sure I'll implement this into my Python Markdown tools even if it doesn't become part of the "official" Markdown spec. I need it too badly (I really don't want to have to move to ReST just yet).

[Uche Ogbuji]

via Copia
6 responses
"This is not to say that the need for footnotes is minute, but rather that the need for footnotes can easily be seen as one aspect of a more general problem in expression."

Not really. Won't I be stuck doing something like this?


1: {@id=fn1} my footnote [&uarr;](#fnref1)

It's no improvement over, say,

Footnote&lt;sup id="fnref1">[1](#fn1)&lt;/sup>

1: <p id="fn1">my footnote [&uarr;](#fnref1)

Or whatever. Both are horrible, far too complex for normal use, and are barely readable in raw Markdown source. Take a look at the image syntax you quote: you cannot possibly argue with a straight face that it's any better than straight HTML either. I'd argue that it's actually rather worse. A footnote solution like this, however, is a huge improvement over the above:


[^1]: my footnote
"I tried to post this to the Markdown mailing list, but they have a policy of rejecting (not just moderating) non-member mailings."

"I really don't have room to join yet another mailing list."

Isn't that a bit like turning up at a pub, giving your opinion and then running off before you get to hear the responses ;)

On the subject, all suggestions so far have been a bit messy to my eye, and sort of break the idea of Markdown being nice to read before it's parsed. Not saying it's not a good idea, just not perfect.
Thanks for the support. :-)

As regards the “metadata at the top of a document” point, I think John is right in his stance that this doesn’t belong in Markdown. It’s really something that the tool sitting atop is responsible for. If you have a bunch of text files written in Markdown, it might make sense to use RFC822 format for the messages; but you could also, like me, have a bunch of Atom Entry Documents sitting around, in which the metadata is expressed differently; and each other format or tool would in turn have different ways or means of expression or storing metadata.

Putting this into Markdown itself would require an API for the Markdown-embedding application to query Markdown for the data (as opposed to the current situation where Markdown is a pure transform), and would allow redundant and possibily contradictory metadata in container formats which have their own way of expressing it.
More than agreed. It was the sense of my tests back in June 2005.
I wonder if you have seen the version 0.9 of the implementation of Markdown. It's now easy to extend the language for your own need.
Note that {#id} and {.style} are not difficult to remember if you're at all web literate: #id and .class is consistent with CSS syntax. If it got too confusing, just treat #id (as something with header ids) and indicate .style was for css style specs.

CSS editors for a site will know the difference, and can design the style sheets accordingly.