Proposal: Markdown, plugged in

[Michel Fortin]

Le 20 mai 2004, à 14:51, Rad Geek a écrit :

> The general principle is: for a variety of reasons (not just InterWiki 
> links, but also different ways of implementing predefined 
> references/"bookmarks", functions based on explicit Markdown 
> references, ...), Markdown should support implicit references. But 
> there's no good way for Markdown to know what to make of implicit 
> references. So, instead, let's define a simple hook for Markdown to 
> pass the buck back to the module that should know: the content 
> management environment into which Markdown has been dropped. The 
> plugin interface is a simple way to do that. So something like the 
> plugin interface should be incorporated into Markdown.
>
> What do y'all think?

There is still one really big drawback about bookmarks, or any other 
plugin for that matter. They are defined outside Markdown. Since there 
is no way everyone have the same bookmarks, it means that your links 
are dependent of your bookmark file, and thus all your text is tied to 
your current site and it's predefined bookmarks. You cannot simply 
export the text somewhere else and expect it to work.

By the way, there is also a way to do bookmarks while staying outside 
of Markdown. Simply append the bookmark list as a list of named 
references at the end of the file before passing it to Markdown. If you 
save your file this way, the drawback I just mentioned is gone too.

I didn't talk about your "source" plugin in my last mail, but if I had 
done so I would have said I do not like it much. It's quite good as a 
way to reduce the number of URLs you have to write, but it also render 
the unparsed text a lot less readable. One goal of Markdown syntax is 
to be seamlessly readable as text; adding a `source:` special reference 
kind makes the text version a little bit cryptic.

Anyway, there is a way to handle this outside of Markdown too! Scan the 
text for any construct like this:

	[1]: http://www.url.com/some/page.html "Article about something"

And add this at the bottom of the text for each reference (before 
sending it to Markdown)

	[source:1]: http://www.url.com/

Should not be too much difficult to do. Of course, this outline one 
problem with your special kind of reference: there is no way to add a 
title to the link.

* * *

Well, I don't necessarily want plugins to be disallowed. But I also 
think we should not rush such a thing into Markdown. The problem is not 
a technical one: it's about keeping things coherent and readable.

There is already a lot of ways to expand Markdown from the outside. A 
little while ago, I talked about a possible plugin system in "Markdown 
and Mathematics". The argument for it was that it can save processing 
time and coding to plugin makers because of not having to handle code 
blocks and code spans (or in your case links handeling). A new argument 
I have to raise against it this time is that it render the plugin tool 
dependant of Markdown, when this "plugin" could be a standalone tool to 
the benefit of even non-markdown users.

Adding plugins to Markdown also has another effect: it makes things 
harder to use by adding an extra level of plugin to a system having 
already many plugins. (Markdown is intended to be used as a plugin)

So to summarize, here are the arguments for plugin support into 
Markdown:

1.	Improved performance because of the code blocks and spans parsing
	only done once.
2.	Allow doing some special things with links references and maybe other
	constructs that would be impossible otherwise.

... and arguments against plugin support:

1.	Programs that post-process the HTML after Markdown has generated it
	is also useful to those not using Markdown (think about something like
	SmartyPants).
2.	Markdown would become more complex and would add one more level
	of plugins to be confused with.

And that bring the question: is plugin support really needed? The more 
I think of it the less desirable it appears to me. Markdown is 
GPLicenced so nothing prevent it to be hacked into different versions 
that extend or change some of it. But that would encourage to keep 
additions outside of Markdown code, as a pre- or post-processor.

The future of Markdown belongs to John Grubber, and he stated that for 
now he is not adding features before reaching 1.0. So we still have 
time to come to a great plugin concept. This also give us time to 
explore other means of expanding Markdown by writing "complements" that 
pre/post-process the text.


Michel Fortin
michel.fortin at michelf.com
http://www.michelf.com/