# Ordered list detection has precedence over title detection **URL:** \ **Category:** Spec\ **Tags:** release-1.0\ **Created:** [June 28, 2015, 3:09am UTC](https://talk.commonmark.org/t/ordered-list-detection-has-precedence-over-title-detection/1251 "2015-06-28T03:09:00Z")\ **Posts on this page:** 20\ **Page:** 1
**Author:** ![tremby](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/tremby/32/735_2.png) [@tremby](https://talk.commonmark.org/u/tremby)\ **Post date:** [June 28, 2015, 3:09am UTC](https://talk.commonmark.org/t/ordered-list-detection-has-precedence-over-title-detection/1251/1 "2015-06-28T03:09:00Z")
I’m not sure if this belongs in spec or implementation, since I don’t have time to dig through the spec at this moment. I had a client just asking me why the German version of one of her pages is displaying so differently from the English. It’s a list of dates and events on those dates. The English: ``` July 1 ------ - Event 1 - Event 2 July 2 ------ - Event 3, etc ``` The German: ``` 1. Juli ------ - Event 1 - Event 2 2. Juli ------ - Event 3, etc ``` The English is rendered as I expect, with h2 titles and unordered lists beneath each. But in the German since they lines start with a number and dot they’re interpreted as ordered lists, and then the hyphens underneath make a horizontal rule. Is this really what’s intended? I’m aware I can do `## 1. Juli` instead to get the effect I’m looking for, or escape the dot like `1\. Juli`. But it seems to me that the underlined title syntax should have precedence over an ordered list. ---
**Author:** ![Knagis](https://cdn.commonmark.org/letter_avatar_proxy/v2/letter/k/ba9def/32.png) [@Knagis](https://talk.commonmark.org/u/Knagis)\ **Post date:** [June 29, 2015, 5:56pm UTC](https://talk.commonmark.org/t/ordered-list-detection-has-precedence-over-title-detection/1251/2 "2015-06-29T17:56:25Z")
The same issue is present in many languages and is much broader than just the titles. In the past the more common case has been a paragraph that start with the year: English: ``` In the year 1985 ... ``` Latvian (and probably many more): ``` 1985. gadā ... ``` ---
**Author:** ![tremby](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/tremby/32/735_2.png) [@tremby](https://talk.commonmark.org/u/tremby)\ **Post date:** [June 29, 2015, 11:05pm UTC](https://talk.commonmark.org/t/ordered-list-detection-has-precedence-over-title-detection/1251/3 "2015-06-29T23:05:24Z")
Yes, I’ve noticed that in the past. In those cases it’s a little more obvious what went wrong. In the case of the title the presence of the line of dashes below really seems to me that it makes the intent extremely clear. In any case, would a possible solution be to only treat it as an ordered list if at least two items are found? ---
**Author:** ![chrisalley](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/chrisalley/32/906_2.png) [@chrisalley](https://talk.commonmark.org/u/chrisalley)\ **Post date:** [June 30, 2015, 6:24am UTC](https://talk.commonmark.org/t/ordered-list-detection-has-precedence-over-title-detection/1251/4 "2015-06-30T06:24:07Z")
> [@Knagis](#): > > The same issue is present in many languages and is much broader than just the titles. In the past the more common case has been a paragraph that start with the year: Starting a title with a number is a common scenario, as sections may be numbered. It is much less common for a paragraph to start with a number followed by a full stop unless the paragraph is intended to be a list item. This issue is similar to [hashtags at the start of a line vs atx-style headers without a space](http://talk.commonmark.org/t/heading-not-working/819). As argued in that topic, requiring a space after a header marker makes the document look cleaner. Similarly, requiring a blank line (to end the preceding list) produces a cleaner looking document and would simultaneously solve @tremby’s issue. ---
**Author:** ![tremby](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/tremby/32/735_2.png) [@tremby](https://talk.commonmark.org/u/tremby)\ **Post date:** [June 30, 2015, 6:37am UTC](https://talk.commonmark.org/t/ordered-list-detection-has-precedence-over-title-detection/1251/5 "2015-06-30T06:37:01Z")
> [@chrisalley](#): > > Similarly, requiring a blank line (to end the preceding list) produces a cleaner looking document and would simultaneously solve @tremby’s issue. Not sure I follow. Where exactly in my example would this blank line be looked for? Do I already have it? ---
**Author:** ![chrisalley](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/chrisalley/32/906_2.png) [@chrisalley](https://talk.commonmark.org/u/chrisalley)\ **Post date:** [June 30, 2015, 11:47am UTC](https://talk.commonmark.org/t/ordered-list-detection-has-precedence-over-title-detection/1251/6 "2015-06-30T11:47:31Z")
Sorry, I thought you had an _ordered_ list in your example. I was actually referring to your comment about treating the “2. Juli” line as an ordered list if at least two items are found. Something like this might be an appropriate solution: This creates an ordered list and a horizontal rule: ```markdown 1. First ordered list Item 2. Second ordered list item --- ``` This creates an ordered list and a header: ```markdown 1. Ordered List Item 2. Second level heading --- ``` In other words, the blank line ends the first list and a second list is only started if the line isn’t followed by the hyphens. Alternatively, lines that start with a number and full stop followed directly by a line containing the hyphens could always be treated as a second level header. But this seems more likely to break backward compatibility. ---
**Author:** ![jgm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\ **Post date:** [June 30, 2015, 4:08pm UTC](https://talk.commonmark.org/t/ordered-list-detection-has-precedence-over-title-detection/1251/7 "2015-06-30T16:08:42Z")
This is a good case. Here are [some related ones](http://johnmacfarlane.net/babelmark2/?normalize=1&text=1.+foo%0A------%0A%0A%3E+foo%0A-----%0A%0A%23+foo%0A-----%0A). The relevant part of the spec is the first paragraph of the Setext Headers section: > A setext header consists of a line of text, containing at least one non-space character, with no more than 3 spaces indentation, followed by a setext header underline. **The line of text must be one that, were it not followed by the setext header underline, would be interpreted as part of a paragraph: it cannot be interpretable as a code fence, ATX header, block quote, horizontal rule, list item, or HTML block.** ---
**Author:** ![tremby](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/tremby/32/735_2.png) [@tremby](https://talk.commonmark.org/u/tremby)\ **Post date:** [June 30, 2015, 10:45pm UTC](https://talk.commonmark.org/t/ordered-list-detection-has-precedence-over-title-detection/1251/8 "2015-06-30T22:45:25Z")
> [@jgm](#): > > This is a good case. Here are some related ones. > > The relevant part of the spec is the first paragraph of the Setext Headers section: Thanks for pinning down the relevant part of the spec, jgm. So my question is now whether this particular part of the specification is good. Do you know the reasons behind it? I stick by my opinion that setext headers should have a higher precedence than the other sort of structures the quotation from the specification lists, not least because it looks so visually striking. I can’t imagine anybody looking at the example markdown in my original post and seeing those a being anything but headings. ---
**Author:** ![tremby](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/tremby/32/735_2.png) [@tremby](https://talk.commonmark.org/u/tremby)\ **Post date:** [June 30, 2015, 10:46pm UTC](https://talk.commonmark.org/t/ordered-list-detection-has-precedence-over-title-detection/1251/9 "2015-06-30T22:46:49Z")
> [@chrisalley](#): > > In other words, the blank line ends the first list and a second list is only started if the line isn’t followed by the hyphens. This seems reasonable to me. > [@chrisalley](#): > > Alternatively, lines that start with a number and full stop followed directly by a line containing the hyphens could always be treated as a second level header. But this seems more likely to break backward compatibility. Yes, this does not seem so reasonable. Seems like a very special exception which could catch people off guard. ---
**Author:** ![jgm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\ **Post date:** [July 1, 2015, 3:46am UTC](https://talk.commonmark.org/t/ordered-list-detection-has-precedence-over-title-detection/1251/10 "2015-07-01T03:46:53Z")
> [@tremby](#): > > So my question is now whether this particular part of the specification is good. Do you know the reasons behind it? I stick by my opinion that setext headers should have a higher precedence than the other sort of structures the quotation from the specification lists, not least because it looks so visually striking. I can’t imagine anybody looking at the example markdown in my original post and seeing those a being anything but headings. It’s a very reasonable question. I agree that, in many cases at least, one would naturally expect ``` 1. Foo ------- ``` to be a header. However, there are many factors to balance here. One is uniformity. The current rule is clear and uniform. If we allowed the example above to be a header, what about the other cases? Should this be a header? ``` ---- ---- ``` What about this? ``` > bar ----- ``` What about ``` code ---- ``` I think it’s a bad idea to have a rule that’s very complicated with lots of exceptions (which is where @chrisalley’s suggestion is going). Another consideration is parsing (though I’d give this secondary weight). The current spec allows us to use a very elegant method for parsing blocks; we can do it line by line, discarding the input after each line, with no lookahead whatsoever. Allowing headers whose contents could be lists complicates this considerably. (This is a secondary consideration, because we could use a different parsing algorithm that looks ahead one line.) Bottom line is that I’m open to reconsidering this, but I don’t think it’s obvious what a better rule would look like. ---
**Author:** ![tremby](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/tremby/32/735_2.png) [@tremby](https://talk.commonmark.org/u/tremby)\ **Post date:** [July 3, 2015, 7:58am UTC](https://talk.commonmark.org/t/ordered-list-detection-has-precedence-over-title-detection/1251/11 "2015-07-03T07:58:36Z")
> [@jgm](#): > > The current rule is clear and uniform To a reader of the specification, perhaps. But not to a user. Very few users of Reddit or similar will read the Commonmark spec! The rule in my head, at least, was “if there’s a line of dashes under something it’s a title”, not “as long as it’d otherwise be seen as a paragraph (after testing for these other dozen structures), and there is a line of dashes under, make it a title”. Your other examples are interesting. In order, my gut feelings are that they’d be `

----

`, `

> bar

` and `
code
`. I suppose this means for me that indentation and its effects have a very high precedence, then setext headers are way up there too, and # style headers, blockquotes and so on take less precedence. Having said that, I wouldn’t take major exception to indentation and setext’s precedence being the other way around. It just seems very unlikely you’ll indent a title line even though it won’t have an effect on the output, and put the dashes underneath which won’t be lining up (because they’re not allowed to be indented more than three spaces), intending for a title to be rendered. If an order of precedence isn’t enough, or it is too complicated as a rule (though I hardly think so: schoolchildren deal easily for the most part with the order of precedence of basic mathematical operators, for example), and things still get ambiguous I would encourage requiring blank lines (or start/end of file) around things. Things look awfully cluttered without them anyway, when viewing as plain text. I realize this would probably shake things up quite a bit, but it seems to me it’d solve a lot of the problems. If horizontal rule and blockquote required blank lines before and after, for example, the first and second examples are no longer ambiguous. Indented code could require them too, and setext headers, and groups of list items. > [@jgm](#): > > Allowing headers whose contents could be lists complicates this considerably Just to make sure we’re clear, I’m not suggesting things should be nested like that. I’m aware that some things can be nested already (I’d hazard a guess that it’s only span things like italic and bold?), but I don’t think HTML even allows block level things like lists within heading tags, off the top of my head. No, I’d definitely be expecting the likes of `

1. Foo

`. ---
**Author:** ![chrisalley](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/chrisalley/32/906_2.png) [@chrisalley](https://talk.commonmark.org/u/chrisalley)\ **Post date:** [July 3, 2015, 12:50pm UTC](https://talk.commonmark.org/t/ordered-list-detection-has-precedence-over-title-detection/1251/12 "2015-07-03T12:50:59Z")
> [@jgm](#): > > It’s a very reasonable question. I agree that, in many cases at least, one would naturally expect > > 1. Foo > > * * * > > to be a header. However, there are many factors to balance here. One is uniformity. The current rule is clear and uniform. If we allowed the example above to be a header, what about the other cases? Should this be a header? > > * * * > > * * * > > What about this? > > ## \> bar > > What about > > ``` > code > > ``` > > * * * I’m in favour of all of these cases producing a header. This is consistent with Markdown.pl and a number of other existing implementations. CommonMark would be in good company. The original Markdown syntax guide says this about horizontal rules: > You can produce a horizontal rule tag (`
`) by placing three or more hyphens, asterisks, or underscores on a line by themselves. This doesn’t exclude the header taking precedence over the horizontal rule. It’s ambiguous. I agree with @tremby that horizontal rules look cluttered without blank lines surrounding them. It is convenient to quickly type some Markdown without adding aesthetically-pleasing whitespace around the horizontal rule. But readability suffers as a result. Markdown’s philosophy is that readability is emphasised above all else. This is another reason to prioritise the header (which makes the markup more readable) over the horizontal rule without a blank line (which makes the markup less readable). ---
**Author:** ![jgm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\ **Post date:** [July 3, 2015, 4:57pm UTC](https://talk.commonmark.org/t/ordered-list-detection-has-precedence-over-title-detection/1251/13 "2015-07-03T16:57:24Z")
The issue won’t be solved by requiring blanks around horizontal rules. With that change, commonmark.js would still not produce a setext header; you’d just get a literal string `---`. [Here’s a nice case](http://johnmacfarlane.net/babelmark2/?normalize=1&text=%3E+%3E+1.+hi%0A%3E+--%0A) that I think illustrates some of the parsing difficulties: ```auto > > 1. hi > -- ``` As this case shows, it’s not enough just to peek at the next line to see if it contains a setext header underline. For the underline might be embedded in nested block quotes and/or list items. Note that [Markdown.pl](http://Markdown.pl) and the like aren’t very consistent about their behavior. [Here’s another “nested” case where you _don’t_ get a setext header](http://johnmacfarlane.net/babelmark2/?normalize=1&text=-+hi%0A++++-+there%0A++++---%0A%0A): ```auto - hi - there --- ``` even though [it works without the nesting](http://johnmacfarlane.net/babelmark2/?normalize=1&text=-+there%0A---%0A%0A). ---
**Author:** ![chrisalley](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/chrisalley/32/906_2.png) [@chrisalley](https://talk.commonmark.org/u/chrisalley)\ **Post date:** [July 5, 2015, 10:26am UTC](https://talk.commonmark.org/t/ordered-list-detection-has-precedence-over-title-detection/1251/14 "2015-07-05T10:26:11Z")
If the rule of uniformity is to be followed here, I’d expect for the behaviour to carry over on different list and quote levels. E.g. check if the next line contains a setext header underline and is intended the same amount. I can see this getting complicated to parse, but if the text is more readable then perhaps it is worth it. ---
**Author:** ![codinghorror](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/codinghorror/32/2_2.png) [@codinghorror](https://talk.commonmark.org/u/codinghorror)\ **Post date:** [January 3, 2016, 10:37am UTC](https://talk.commonmark.org/t/ordered-list-detection-has-precedence-over-title-detection/1251/15 "2016-01-03T10:37:02Z")
Given ``` 1. Juli ------ - Event 1 - Event 2 ``` Is it really so onerous to ask the user to escape the `.` there? There are a lot of other situations where accidental numbered lists need to be escaped, such as: `1986. What a great season. Perhaps the finest season in the history of the franchise.` and I’m not sure why this one is so special or different, certainly not special or different enough to warrant a ton of special casing and unusual rules. ---
**Author:** ![chrisalley](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/chrisalley/32/906_2.png) [@chrisalley](https://talk.commonmark.org/u/chrisalley)\ **Post date:** [January 3, 2016, 12:51pm UTC](https://talk.commonmark.org/t/ordered-list-detection-has-precedence-over-title-detection/1251/16 "2016-01-03T12:51:57Z")
> [@codinghorror](#): > > Is it really so onerous to ask the user to escape the . there? There are a lot of other situations where accidental numbered lists need to be escaped, such as: > > 1. What a great season. Perhaps the finest season in the history of the franchise. > > and I’m not sure why this one is so special or different, certainly not special or different enough to warrant a ton of special casing and unusual rules. I agree that the situations are similar. That said, the requirement to use the escape character isn’t desirable (for readability reasons) in either case. I posted [a related topic](http://talk.commonmark.org/t/should-single-element-lists-be-supported/1957) regarding list items on their own which might be helpful here (apologies for bringing up yet another spec change proposal so late in the game). ---
**Author:** ![tin-pot](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/tin-pot/32/810_2.png) [@tin-pot](https://talk.commonmark.org/u/tin-pot)\ **Post date:** [January 4, 2016, 5:38pm UTC](https://talk.commonmark.org/t/ordered-list-detection-has-precedence-over-title-detection/1251/17 "2016-01-04T17:38:01Z")
Let me phrase the issue in this way: According to the current specification, we have - ATX heading syntax and - setext heading syntax as two alternative _input syntax_ variations to specify a _heading_ (of level 1 or 2). Given that these options _confer no difference in meaning whatsoever_, and produce the _exact same result_, I’d say that having a “rewrite rule” connecting them would be “desirable”. Consider a string `{string}`, and on the one hand ``` #⎵{string}⎵# ##⎵{string}⎵## ``` compared to ``` {string} ======== {string} -------- ``` It would be IMO “desirable” to impose _as little as possible_ side-conditions on the content or “form” of `{string}` in order to make the re-write rule work, that is: in order to make both input forms in fact equivalent. Now the _ATX heading_ syntax works with pretty much _any_ value for `{string}`: it may contain arbitrarily many NUMBER SIGN characters, even at the start or end (see [example 40](http://spec.commonmark.org/0.23/#example-40)), or start with “`>⎵`”. In fact, I see no other restriction for `{string}` than that it must not straddle input lines. In contrast to that, the _setext heading_ syntax description has a _whole paragraph_ of restrictions on `{string}`: > […] a line of text, containing at least one non-whitespace character, with no more than 3 spaces indentation, followed by a setext heading underline. The line of text must be one that, were it not followed by the setext heading underline, would be interpreted as part of a paragraph: it cannot be interpretable as a code fence, ATX heading, block quote, thematic break, list item, or HTML block. For my taste too, the syntactic side-conditions for `{string}` in _ATX headings_ are _so much weaker_ than those applicable in _setext headings_ that one can in fact ask _why_ this is required. It seems that the weakest possible requirement on `{string}` in _setext headings_ would be that `{string}` is not _blank_: that is, contains a least on _graphical character_. It would then be IMO appropriate to require the `{string}` line and hence the _setext heading_ to be preceded by a _blank line_ (which I would consider reasonable anyway). Consequently, when parsing _CommonMark_, recognition of a line _following a blank line_ as (the starting line of) a: - code fence, - ATX heading, - block quote, - thematic break, - list item, or - HTML block would be “suppressed” **iff** the next line is a _setext heading underline_. Algorithmically, this would require only look-ahead over one input line, and would only be executed in the transition from _blank lines_ to _block of non-blank lines_. In this way, the “rewrite rule” would in fact **“always”** work—except in the “degenerate” case when `{string}` is a null string, or consists of _white space_ only. But it seems that this exception can not be avoided in order to still allow recognition of a _thematic break_ (formerly known as `
`, or _harsh rupture_ 😉 ) comprising only HYPHEN-MINUS characters. ---
**Author:** ![jgm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\ **Post date:** [January 5, 2016, 10:41pm UTC](https://talk.commonmark.org/t/ordered-list-detection-has-precedence-over-title-detection/1251/18 "2016-01-05T22:41:14Z")
> [@codinghorror](#): > > There are a lot of other situations where accidental numbered lists need to be escaped, such as: > > 1. What a great season. Perhaps the finest season in the history of the franchise. > > and I’m not sure why this one is so special or different, certainly not special or different enough to warrant a ton of special casing and unusual rules. I worry, though, that this case – numbered section headings – is exceptionally common, so asking authors to escape here is onerous. Keep in mind, also, that there may be a large number of existing Markdown documents that have numbered setext section headings, and these might all be broken by the current CommonMark behavior. ---
**Author:** ![codinghorror](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/codinghorror/32/2_2.png) [@codinghorror](https://talk.commonmark.org/u/codinghorror)\ **Post date:** [January 5, 2016, 11:03pm UTC](https://talk.commonmark.org/t/ordered-list-detection-has-precedence-over-title-detection/1251/19 "2016-01-05T23:03:28Z")
Maybe but since we’ve decided that `#heading` is no longer a heading (the space is required), some similar adjustment to headers in the form of ``` 2. Second level heading --- ``` wouldn’t be too surprising, would it? Headers are, by definition, not super common elements in a document, so changing them is a bit easier than something that affected every para in a document. ---
**Author:** ![tin-pot](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/tin-pot/32/810_2.png) [@tin-pot](https://talk.commonmark.org/u/tin-pot)\ **Post date:** [January 5, 2016, 11:32pm UTC](https://talk.commonmark.org/t/ordered-list-detection-has-precedence-over-title-detection/1251/20 "2016-01-05T23:32:36Z")
Sorry, but I have to ask: how are “`1986.␣What a great season.`” and “`2.␣Second level heading`” examples for _numbered section headings_? I thought they were _ordered list items_ the moment before? If one has the—IMO misguided, although eg IEEE does it too—desire to ignore most modern style guides and to use the string “`2.␣Second level heading`” as a _section heading_, then I’d say it’s nothing else but just to require the input syntax: ``` 2\.␣Second level heading ------------------------- ``` In any case, there’s still _setext_, where no escaping is needed already today: ``` ##␣2.␣Second level heading␣## ``` So that desire seems a weak reason to change the rules, for my taste. [Next page](https://talk.commonmark.org/t/ordered-list-detection-has-precedence-over-title-detection/1251.md?page=2)