Ordered List Syntax Suggested Change

John Gruber gruber at fedora.net
Fri Mar 12 23:54:46 EST 2004


Sean Santry <markdown at seansantry.com> wrote on 03/12/04 at 9:56a:

> Though markdown somewhat addresses this by allowing me to use repeated 
> or out-of-sequence numbers, I find it odd that I might write in a text 
> file
> 
> 3563. First
> 33. Second
> 900309237515. Third
> 
> and produce an HTML document that renders as
> 
> 1. First
> 2. Second
> 3. Third

Sure, that would definitely be odd. But the oddity wouldn't be in
Markdown's behavior -- it'd be in the fact that you wrote such an
oddly-numbered list.

I considered this quite a bit when I decided to use real ordinals
for marking ordered lists. There's an inherent discontinuity if you
write your list in Markdown using real numbers, but produce HTML
where each list is just another `<li>`.

But I concluded that it isn't worth worrying about garbage input.
It's only worth worrying about things real people might actually
write.

E.g., I really *am* worried about the fact that people might write:

    1984. What a great year.


> I noticed that `+' isn't used in the current syntax. May I suggest 
> using it in an alternate syntax for those of us who wish to ignore the 
> numbers in their ordered lists?
> 
> This
> 
> + First
> + Second
> + Third

But that doesn't look like a numerically ordered list. It looks like
a bulleted list.

The first rule of Markdown is: You do not talk about Markdown. No,
wait, that's Fight Club. The first rule is:

**Markdown's formatting syntax looks like what it means.**

And, actually, I plan to add `+` and `-` as optional characters you
can use instead of `*` for unordered lists.

What I *might* consider is something like this:

1.  First
#.  Second
#.  Third

You would still have to start your list with a real number. But you
could use a hash mark instead of a number for any subsequent items
in that list. I think we could squeeze this by Markdown's First Rule
because '#' often means "number".

One thing I'm definitely going to add support for is starting an
ordered list at a number other than 1. That's why no matter what,
you'll need to start your lists with a number.

* * *

But here's what I suggest you do if you really don't want to keep
your ordinals accurate in your source: use zeros for every list
item. E.g.:

0.  one
0.  two
0.  three

That's pretty clearly disambiguated from the "false numbering"
problem you'd run into if you were using real numbers and decided to
move them around or add new items. But it still looks like a
"numbered list", and, most importantly, it already works. :^)


> And this
> 
> X+ First
>   + Second
>   + Third
> 
> could produce
> 
> X. First
> Y. Second
> Z. Third
> 
> Thoughts?

Lettered ordered lists are also definitely on the list for future
features. But the syntax will probably be like numbered lists now:

a.  First
b.  Second
c.  Third

And you could start with whatever letter you want.

-J.G.


More information about the Markdown-discuss mailing list