0

I have the following markdown snippet which will be visible on Github:

1. Ask a supervisor for a `cmprod.pem` file and move it into the `~/.ssh` folder.
2. Run `chmod 600 ~/.ssh/cmprod.pem`
3. Run `eb ssh` and type `yes` when it asks if you would like to add the key to your keychain.
4. Once connected via SSH, to access the application's source code, perform the following steps
    - `sudo docker ps`
    - Copy the desired value from the `CONTAINER ID` column
    - Run `sudo docker exec -it $CONTAINER_ID rails c` using the copied value.

The problem is that the nested list (the three bullet points under step 4) are not formatting correctly. They end up looking like this:

  1. Ask a supervisor for a cmprod.pem file and move it into the ~/.ssh folder.
  2. Run chmod 600 ~/.ssh/cmprod.pem
  3. Run eb ssh and type yes when it asks if you would like to add the key to your keychain.
  4. Once connected via SSH, to access the application's source code, perform the following steps    - sudo docker ps    - Copy the desired value from the CONTAINER ID column
    • Run sudo docker exec -it $CONTAINER_ID rails c using the copied value.
Improve this question

1 Answer 1

Reset to default
1

This depends on which ruleset you are using. According to Commonmark, which GitHub uses (and I'm assuming is relevant here due to the [github] tag), "a list can interrupt a paragraph. That is, no blank line is needed to separate a paragraph from a following list." And Example 280 of the spec even shows an example similar to yours. If its not working for you with a Commonmark parser, then that would be a bug.

However, if you are not using Commonmark (or as a workaround to any Commonmark bug), then the Markdown rules require you to have a blank line between a list and the preceding paragraph. As the text in item 4 of your parent list would be a paragraph (inside the list item), then that paragraph and the child list item which follows the paragraph would need to have a blank line between them. Like this:

1. Ask a supervisor for a `cmprod.pem` file and move it into the `~/.ssh` folder.
2. Run `chmod 600 ~/.ssh/cmprod.pem`
3. Run `eb ssh` and type `yes` when it asks if you would like to add the key to your keychain.
4. Once connected via SSH, to access the application's source code, perform the following steps

    - `sudo docker ps`
    - Copy the desired value from the `CONTAINER ID` column
    - Run `sudo docker exec -it $CONTAINER_ID rails c` using the copied value.

It's helpful to remember that when nesting list items, you need to follow all the same rules you would outside of a list. Then just indent one level. So, for example, everything nested in item 4 would look like this outside of a list item:

Once connected via SSH, to access the application's source code, perform the following steps

- `sudo docker ps`
- Copy the desired value from the `CONTAINER ID` column
- Run `sudo docker exec -it $CONTAINER_ID rails c` using the copied value.

You need a blank line between the paragraph and the list. Therefore, when nesting all of that in a list, you need to maintain the same formatting and maintain the blank line. Just because the first line starts after the bullet (or list number) doesn't mean it doesn't follow the same rules.

Finally, even if you are using a Commonmark parser, I would suggest using the blank line. It is just good form which any Markdown linter would suggest.

Improve this answer
Sign up to request clarification or add additional context in comments.

4 Comments

I tried pasting in your first snippet, and it works as described. But I can't figure out why it doesn't work when applied to my md file. Can you take a look at this and let me know how I can edit it so the last list formats correctly? gist.github.com/maxp-edcast/9d7bbf0e28a4666dc2b492403cbc5d3b
Delete the indentation in front of item 2 of your sublist and type four new spaces. Two of the four spaces are not actually spaces but non-breaking spaces (Unicode character xa0), which is confusing Markdown. In fact, whenever a nested list doesn't work, I always check the indentation first. I checked yours before answering (by counting), but didn't notice the non-breaking space characters. When I posted my answer, I deleted the indentation and recreated it, so I didn't encounter your problem.
By the way, I discovered your problem by opening your file in a proper text editor and then turning on all hidden characters. It immediately showed the two non-breaking spaces as being different than all other spaces in the document.
Thanks very much. I have no idea why those characters were entered. I'm on OSX.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.