A reminder of the original design goal of Markdown - my personal thoughts

[Michel Fortin]

About these two forms:

     <h3 id="inlinehtml">Inline HTML</h3>

     ### Inline HTML ###               {#inlinehtml}

Fletcher T. Penney wrote:


> I find the second version to be distracting when read as raw text,  

> and it certainly doesn't follow the original idea of not "looking  

> like it’s been marked up with tags or formatting instructions."


I disagree. I find the second form less "marked up" and more readable  
than than the first. The reason is that the header content (Inline  
HTML) is placed first and isn't mixed with had-to-read metadata. The  
id attribute is somewhat left-aligned and can more easily be ignored  
as "markup" than in the first form where everything is packed and the  
id attribute is shown first.

I think this the id attribute for headers makes a lot of sense since  
you need it to make links to different parts of a document. Event the  
Markdown syntax description document needs this. So it *is*, in my  
view, pretty necessary.

Well, we could argue that what is really necessary is a way to link  
to headers, not to set manually the id attribute of each one. But  
there is many reasons to not want automatic id generation: What  
happen to internal links if you change slightly the name of one  
header? Will adding a new section in the middle of the document break  
outside links to other headers? These two problems cannot appear if  
you set your own id and do not change them.

Now, I also think you have a good point: there is no reason to allow  
this syntax everywhere if it is not needed. While I think the id  
attribute is pretty necessary for headers, I'm less sure about other  
attributes and other elements. Currently, I see these as "important":

*   Cite attribute for blockqutoes
*   Image width and height (maybe)
*   Class attribute (do we need this absolutely everywhere?)

(Did I forgot something?)


> Otherwise, I envision myself (and other "purists" if there are any)  

> creating a "Markdown Lite" that removes any additions that don't  

> fit the original plan.  If the project is going to deviate from  

> this plan, I believe it should at least deviate on purpose.  Not  

> through the slow unchecked feature-bloat of time.


I think for that to be successful, such a Markdown Lite would need to  
be either

1.  significantly faster that a "bloated" Markdown; or
2.  standard Markdown would need to cause enough trouble to people
     not using the "advanced features" to make them switch.

The first condition will probably be hard to achieve without a total  
rewrite since I think the parts of Markdown that are most time- 
consuming right now are for working around inline HTML. This include  
HTML produced by Markdown's own conversion of its syntax, so you  
cannot remove inline HTML support and say it will run faster.

The second condition presume a Markdown with more features will be  
less usable. I somewhat doubt this: the Markdown syntax says you  
don't have to use every features and I don't see this changing. If  
you prefer to write `<strong>` instead of `**`, do it; if you prefer  
to write `<h3 id="somehting"></h3>` instead of `### {#something}`,  
just do so.


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