(doc) Documentation markdown must have a blank line before lists

[robinzimmermann]

The following markdown happens to render correctly in GitHub, but it isn't "standard" and isn't portable.

(This markdown snippet was taken from gateway/doc/about/about.md):

This topic contains the following sections:

• Text Conventions
• About URI Syntax
• About Ports
• About KAAZING_HOME
• About GATEWAY_HOME

There needs to be a blank line before the first line item:

This topic contains the following sections:

- Text Conventions

• About URI Syntax
• About Ports
• About KAAZING_HOME
• About GATEWAY_HOME

While the original snippet will work in GitHub, it does not work in Jekyll, which is converting the markdown to HTML for the website.

I believe any lists in the documentation will need to be updated to have a blank line inserted before the first list item.

[ghost]

@robinzimmermann , since we've decided against the Jekyll conversion route, can I close this issue?

[robinzimmermann]

In my opinion this still needs to be done. I tested the markdown in some online markdown validators and none of them liked having lists without a blank line. I think it might be only Github that handles lists without a blank above it.

[ghost]

But if Github is fine with it, what does it matter what some other implementations want? It's valid in GitHub (ergo, it should be valid in Jekyll since Jekyll claims to be a Github Pages tool). I'd like to wait until it becomes a problem with whatever conversion tool we use.

[robinzimmermann]

ergo, it should be valid in Jekyll since Jekyll claims to be a Github Pages tool

False assumption. I thought the same thing, but no. GitHub's rendering of markdown to HTML seems different than what Jekyll is using.

BTW, the claim that GitHub Pages makes is not that the markdown renders the same. It is if you use the same version of Jekyll, Ruby, and other modules that GitHub uses, then when your pages are rendered by GitHub they will look the same as how it looks to you in your local development environment.

I'd like to wait until it becomes a problem with whatever conversion tool we use.

The only way to avoid the problem is to edit in a text editor and see it rendered in GitHub when you check it in. Anyone editing the doc locally using a markdown tool to visualize it will have this problem.

I also suspect that we will end up converting markdown to HTML using some build tool, which will also have the same problem.

This issue can prioritized as needed, but I think it should stay open and be done at some point, and not be closed.

[ghost]

Okay, I'll leave it open.