Open reagle opened 3 years ago
When converting to markdown, I think that rather than formatting lists like:
Lorem ipsum dolor sit amet.
- foo
- bar
- baz
Lorem ipsum dolor sit amet.
(no space before the list marker, and three spaces after) they should instead be formatted like this:
Lorem ipsum dolor sit amet.
- foo
- bar
- baz
Lorem ipsum dolor sit amet.
with two spaces before the list marker and one space after.
In both cases the list content starts at 4-places in. Rationale:
pdf output:
html output:
Nested lists example. Here's the markdown:
Lorem ipsum dolor sit amet.
- foo
- foo a
- foo b
- bar
- bar a
- bar b
- bar b 1
- bar b 2
- bar c
- baz
- moo
Lorem ipsum dolor sit amet.
- foo
- foo a
- foo b
- bar
- bar a
- bar b
- bar b 1
- bar b 2
- bar c
- baz
- moo
Lorem ipsum dolor sit amet.
Here's the pdf output (of course, both styles render identically):
@uvtc
In both cases the list content starts at 4-places in. Rationale:
- indentation before the list marker is how its generally rendered in html and pdf output, and looks better. For reference, see screenshots below of html and pdf output.
- if you don't include any leading indentation before the list marker, then as you scan your eyes down the plain text document, everything looks jammed to the left. It just looks better with that indentation before the marker. And markdown should firstly be natural looking and easy to read.
I have to disagree with this for several reasons:
I think at most this should be an option to enable, like @reagle first quoted @jgm as saying.
Note that in current HEAD, the extra spaces are omitted for commonmark
and gfm
output. They are retained for markdown
output, mostly because this makes the output compatible with a wide range of converters.
I should note that I'm coming at this originally from RStudio Visual Markdown: https://github.com/rstudio/rstudio/issues/11013
Not sure why I didn't mention it above, but as alluded to in the quote from @jgm , following the four-space-rule makes multi-line multi-paragraph list content line up really nicely, and makes it easy to see which list item to which content belongs. Here's an example:
Lorem ipsum dolor sit amet.
* Consectetur adipiscing elit, sed
do eiusmod tempor incididunt ut
labore et dolore magna aliqua.
- nested list item here. Lorem
ipsum dolor sit amet, consectetur
adipiscing elit, sed do eiusmod
tempor incididunt.
- nested list item here. Lorem
ipsum dolor sit amet, consectetur
adipiscing elit, sed do eiusmod
tempor incididunt.
Second paragraph of first list
item. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris.
And here is a
code block
someone added.
Third paragraph of first list item.
Nisi ut aliquip ex ea commodo consequat.
* Second list item. Excepteur sint occaecat
cupidatat non proident, sunt in culpa qui
officia deserunt mollit anim id est laborum.
vanilla
: From the vanilla bean. Lorem ipsum dolor
sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore.
Second paragraph about vanilla!
chocolate
: From the cocoa bean. Et dolore magna
aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi.
* Third list item.
with output:
(last list item didn't make it into the screenshot).
When pandoc converts a list to markdown, the list marker is followed by three spaces. A few people seem to prefer this not be the case. @jgm wrote: