Proposal for footnote GUID syntax

Jonathan Deber jonathan.deber at
Thu Jul 12 16:00:04 EDT 2007

While we're talking about new syntax, I thought that I'd throw out an
idea I had to extend the footnote syntax as it currently exists in
PHP Markdown Extra.

I'm not sure that it's the best way to solve this particular problem,
but I figured I'd throw it out there to get any comments on it.

It relates to the problem of specifying a document's GUID. A few
months back, I wrote:

> Actually, I do have one feature suggestion for the PHP

> Markdown Extra syntax. If you're posting to a CMS system

> where multiple articles may appear on the same HTML page,

> you need to assign each article a GUID so that the footnote

> links make sense (i.e., you can't have two articles that

> both use "fnref" as the anchor name for the footnotes, since

> you would end up with two anchors with the same name if two

> articles are published on the same page). It's of course

> possible to do this with a search and replace of "fnref" to

> something like "2007-01-23-1" prior to publishing. But, it

> would be nice if you could specify a document GUID and have

> the Markdown processor do that substitution for you.

Michel Fortin was kind enough to respond with the following:

> It's already possible if you instantiate the parser yourself

> instead of calling the simplified Markdown function:


> $parser = new Markdown_Parser;

> $parser->fn_id_prefix = $entry_guid;

> $text = $parser->transform($text);

So far so good. However, we're still left with the problem of
deciding on a GUID when we instantiate the parser. This complicates
our workflow, since we can't just pass a block of Markdown text to
the parser and let it do its processing. (We could do something like
taking a hash of the document text and using that as the GUID, but
that generates lengthy and ugly anchor names. It also causes the
anchor names to change if minor corrections are made to the document.)

Ideally, it should be possible to provide some metadata in the
Markdown document itself to provide the parser with a GUID of our

There are two possibilities that come to mind. The first would be to
add in some form of generic metadata syntax, which could then be used
for a variety of other things. However, I think that adding that
sort of syntax goes against the spirit of Markdown (as John puts it,
"[t]he idea is that a Markdown-formatted document should be
publishable as-is, as plain text, without looking like it's been
marked up with tags or formatting instructions"), and leads down a
slippery slope.

The second idea is to add the GUID to our footnote definitions. It
doesn't require adding any new sections to the document, and I think
that it has a minimal impact on the readability of the non-processed
document. It's also easy to parse (and to specify in a formal
grammar, if that ever happens).

Basically, rather than:

> This is some text[^1]. And here's some more[^2].


> [^1]: Which has an interesting footnote.

> [^2]: Which has a less interesting footnote.

you'd have:

> This is some text[^1]. And here's some more[^2].


> [^1 guid="foo"]: Which has an interesting footnote.

> [^2]: Which has a less interesting footnote.

You could also do something like [^1 documentID="foo"], which might
be more readable. Note that we only need to specify the GUID a
single time, probably in our first footnote.

Anyway, as I mentioned, I'm not sure that this is the best choice of
syntax to solve this problem, but it is one option.

I'd appreciate any thoughts.

(As a side note, it occurs to me that "GUID" is the wrong term to be
using, since the ids in question aren't necessarily globally unique.
Perhaps we should use "UID"? Or something else?)


Jonathan Deber
jonathan.deber at

More information about the Markdown-Discuss mailing list