CODEWITHSUNDEEP
githubmarkdown
Dane Powell
Dane Powell

Reputation: 651

Markdown formatting of code blocks in lists

I'm trying to determine if I'm doing something wrong, or if there's a bug with common Markdown processors.

I have the following markdown code (source):

1. Verify that your system meets the [system requirements for BLT](../INSTALL.md)
1. [Fork](https://help.github.com/articles/fork-a-repo) the primary GitHub repository
1. Clone your fork to your local machine:

         git clone [email protected]:username/project-repo.git
         git remote add upstream [email protected]:acquia-pso/project-repo.git

1. If your project uses separate `master` and `develop` branches, checkout the `develop` branch: `git checkout develop`
1. Run `composer install` (you must already have Composer installed).
1. Install `blt` alias: `composer blt-alias`

You can see how this renders here:

  1. Verify that your system meets the system requirements for BLT
  2. Fork the primary GitHub repository

  3. Clone your fork to your local machine:

     git clone [email protected]:username/project-repo.git
 git remote add upstream [email protected]:acquia-pso/project-repo.git

  4. If your project uses separate master and develop branches, checkout the develop branch: git checkout develop

  5. Run composer install (you must already have Composer installed).
  6. Install blt alias: composer blt-alias

Inspect the HTML and notice how list items 3 and 4 are enclosed in paragraph blocks, while the other list items are not. This can cause very inconsistent styling depending on the CSS used.

I'm just wondering why Markdown places some list items in paragraphs and not others? I can replicate this behavior here on Stackoverflow, on Github, and on Readthedocs (which looks the worst).

Upvotes: 2

Views: 2432

Answers (2)

mb21
mb21

Reputation: 39219

The closest thing to a markdown standard is CommonMark and it says:

A list is loose if any of its constituent list items are separated by blank lines, or if any of its constituent list items directly contain two block-level elements with a blank line between them. Otherwise a list is tight. (The difference in HTML output is that paragraphs in a loose list are wrapped in <p> tags, while paragraphs in a tight list are not.)

Different markdown parsers handle these things differently, but since your third item contains a code block, at least that item will be wrapped in a <p> tag. According to CommonMark, all list items should then be wrapped in paragraphs though.

Either way, you can force all <p> tags by separating the list items by newlines:

1. Verify that your system meets the [system requirements for BLT](../INSTALL.md)

1. [Fork](https://help.github.com/articles/fork-a-repo) the primary GitHub repository

1. Clone your fork to your local machine:

         git clone [email protected]:username/project-repo.git
         git remote add upstream [email protected]:acquia-pso/project-repo.git

1. If your project uses separate `master` and `develop` branches, checkout the `develop` branch: `git checkout develop`

1. Run `composer install` (you must already have Composer installed).

1. Install `blt` alias: `composer blt-alias`

Upvotes: 1

Dave
Dave

Reputation: 1378

The paragraphs are only on items 3 and 4. #3 has one because of the code block--I don't think there's any way around that [0]. #4 has one because of the extra line after the code block.

Here's a gist that has no paragraph on item #4.

[0] I'm no HTML expert, but because the code block requires a <pre>, the preceding text probably needs to be in a <p>. See inline vs block-level elements.

Upvotes: 3

Related Questions