Closed nmalky closed 6 years ago
I think this is due to the different standards of markdown syntax. e.g
* This is a bullet point
vs.
- This is a bullet point
I'm pretty sure that Hugo (our static site generator) uses the latter.
Hmm, this seems problematic. GitHub seems to render - Bullet point
, but with more spacing:
(edit: rather with mixing between *
and -
)
* Bullet point with asterisks
:
- Bullet point with hyphen
:
We could fix this by enforcing use of -
everywhere, but this seems like a bad idea to have to change everything
Is there a workaround for Hugo?
I'm not exactly sure why this is happening, but rather than trying to find a weird solution, let's just enforce -
(massive bikeshed, but here goes)
I actually prefer *
over -
, mostly as it looks like a bullet.
The original markdown spec notes that they're equivalent.
Usually the issue is that the is some missing space, either on the preceding line or on the same line as the bullet. Note that the example in the issue description is buggy in this manner as it says:
* point1
*point2
which is fairly obviously wrong. Surely a better fix here is to (shocker) actually look at the render before committing and when reviewing?
@PeterJCLaw Apologies. The issue description example code was made up inexactly, and I should have just referenced the actual code. See https://github.com/sourcebots/volunteer-docs/pull/5/files and the corresponding render preview in https://deploy-preview-5--sourcebots-volunteer-docs.netlify.com/essential-knowledge/how-to-contribute-code/.
It appears the actual problem is just the lack of spaces before the list of bullets. i.e.
This list doesn't render as intended:
* point1
* point2
This actually renders with bullet points.
* point1
* point2
Essentially: I just didn't use paragraphs properly. https://daringfireball.net/projects/markdown/syntax should go somewhere in these docs.
Edit: Now fixed by https://github.com/sourcebots/volunteer-docs/pull/5/commits/cf37fb063e72a29a69c6fd36aaa154dfb83325e3.
The whitespace between the text and the bullet points is pretty large, though, but that's another matter. Another issue, maybe?
Not sure what part of the codebase is causing this, but anyway:
The markdown previews for
how-to-contribute-code.md
don't match between GitHub and the Netlify preview. Specifically, GitHub renders* point1\n *point2
as bullet pointed lines, but the preview just shows all the bullet points on one line as " point1 point2"See: https://deploy-preview-5--sourcebots-volunteer-docs.netlify.com/essential-knowledge/how-to-contribute-code/