Extra lines appearing between list items in Github Markdown

Question

I have a Readme with a half dozen lists.

Everything works fine until the second to last list. The problem is that an extra newline appears between those list items. This will be more clear with a screenshot:

I am using the Markdown Preview package in sublime text and I see the same formatting issue if I preview using the Github Markdown preprocessor.

What's most weird, though, is that I don't see the same issue if I type my text into https://jbt.github.io/markdown-editor

If you would like to try yourself, use the following string:

_git_

- **gl**: `git log <optional args>` _shows the revision history_
- **gpoh**: `git push origin head` _pushes the current branch_
- **gpom**: `git push origin master` _pushes the master branch_
- **grv**: `git remote -v` _lists the remotes_
- **gs**: `git status` _shows unstaged & staged changes_
- **gacm**: `git add -A; git commit -m "<message>"` _commits all changes with a message_
- **gacm-lfs**: `sudo git add -A; sudo git commit -m <message>` _it might not be this way for everyone,
  but for me `sudo git` uses git-lfs (git large filesystem) while `git` uses regular git. This function
  adds and commits all files with a message in a git-lfs repo._
- **gc**: `git checkout <branch>` _changes branches_
- **gclo**: `git clone <repo>` _clones a repo_
- **get_branch**: `git branch -f origin/<branch>; git checkout <branch>` _gets a specific branch from a remote repo_

_fish meta functions_

- **backup_functions**: `cd ~/.config/fish/functions; git add -A; git commit -m "<message>"; git push origin master; cd -` _backups the functions folder into a repo_
- **cdfns**: `cd ~/.config/fish/functions` _changes into the functions dir_
- **cfn**: `cat ~/.config/fish/functions/<name>.fish` _shows the definition of a function_
- **efn**: `nano ~/.config/fish/functions/<name>.fish` _edits a function's definition (using nano)_
- **fn**: `echo -e "function $argv[1]\n  $argv[2]\nend" > ~/.config/fish/functions/$argv[1].fish` _create a function_
- **fns**: `ls ~/.config/fish/functions` _list functions_
- **rmfn**: `rm ~/.config/fish/functions/<name>.fish` _remove a function_
- **fndoc**: `echo -e "- <text>" >> ~/.config/fish/functions/README.md` _adds a line to the readme documenting a function_
- **fs**: `funcsave <name>` _alias for funcsave, e.g.:_

      function fs
        funcsave $argv
      end
      fs fs

Answer 1

Your first list is a "tight" list while the second is a "loose" list because it contains a codeblock in one of the list items. If you want the lists to match, use the same type for both. Adding a blank line between items on the first list will cause them to match. As the spec explains:

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.)

As a simple example, this list:

* line 1
* line 2

would be rendered to this HTML:

<ul>
    <li>line 1</li>
    <li>line 2</li>
</ul>

Whereas this list:

* line 1
* line 2

  a second block

Would be rendered as:

<ul>
    <li>
        <p>line 1</p>
    </li>
    <li>
        <p>line 2</p>
        <p>a second block</p>
    </li>
</ul>

Notice that the second list item contains multiple paragraphs. Therefore each paragraph in the the list item is wrapped in <p> tags, making the list a "loose" list. For consistency, all items in the list are then wrapped in <p> tags (including the first item). While that example uses a paragraph, the same applies to any blocklevel construct, including the codeblock in your example.

You can also force a list to be a "loose" list by adding a blank line between list items. For example, this list:

* line 1

* line 2

Results in this HTML:

<ul>
    <li>
        <p>line 1</p>
    </li>
    <li>
        <p>line 2</p>
    </li>
</ul>

Therefore, if you add a blank line between at least two of the items in your first list, both lists will consistently be displayed with some white space between them.

The reason that wrapping the content of the list item in <p> tags adds white space is that the styles for the page (CSS) have defined padding and/or margin for <p> tags. One could edit the CSS to remove this padding/margin on their own site, but on third party hosts, that is generally not an option.

As for why some tools do not seem to exhibit this behavior; it could be that they have default CSS styles which cause both types of lists to look the same (StackOverflow does this for example). The other possibility is that they are using an old-school Markdown parser rather than the much newer CommonMark spec (which GitHub uses). The original Markdown rules also had the concept of loose and tight lists, but the behavior was not so specifically defined so different implementations behaved slightly differently. Many followed the reference implementation and only made the list items adjacent to blank lines "loose" and all other items "tight". In your example only the last item would be "loose" but, as it is the last item in the list, would not be as noticeable. For a comparison of how various implementations behave, see Babelmark.

Regardless of implementation, if you want "tight" lists, the only way to always get that is to never include any blank lines anywhere in your list items. That means that you can never nest other block level constructs, with a few very specific exceptions:

1. The obvious exception would be nested lists, but even then, you would need to avoid blank lines (see example):

   * parent item
       * nested item
       * Another nested item
   * sibling of parent
   * Another sibling of parent
   

2. A nested codeblock or blockquote can be nested in some implementations, but it needs to start on the first line of the list item and contain no blank lines.

   * list item
   *     A code block because it is indented appropriately
   * > a blockquote
   * a list item
   

   As you can see in that example, it only works in some implementations. Notably, the CommonMark implementations. In other words it will work on GitHub, but it may not with other tools or on other sites.

Regardless, you can not have a a tight list if you have multiple child paragraphs, code blocks, and/or blockquotes.