Coding style for markdown files

jiskattema commented 6 years ago

Our markdown files do not follow a coding style themselves, and look quite messy.

Do we have a newline after each header?
Newline after a line ending ([.?!]), or do we wrap at 80 characters (this is actually happening at places. i approve of this fortran70 inspired behaviour, but would not use it here ;)

jiskattema commented 6 years ago

is there a linter for markdown? Some quick searching gives https://github.com/remarkjs/remark-lint

egpbos commented 1 year ago

Perhaps some short suggestions could be written down, although I'm afraid they won't be adhered to much, and it also doesn't feel completely like our business to say too much on this, since I wouldn't technically call it software (although I admit it's a gray area); MarkDown is primarily a markup language, as well as HTML and LaTeX, and so the rendering is more important than the source and gets the most attention. Should we also give suggestions on how to write those? I'm not completely convinced. Also, there's a big risk that many rules are opinionated.

Like with #54, I would suggest that if someone wants to pick this up, they first do a bit more research into what good practices are out there for markup languages in general (let's not do MarkDown only). Then try to brainstorm about it with a few people (preferably with different opinions) and see if you can get to some agreement. Don't write the chapter text yet, first discuss it here, so we can decide whether this should become a chapter or not.

egpbos commented 1 month ago

Maybe interesting to add to precommit https://github.com/executablebooks/mdformat

Perhaps we can also run it automatically after PRs and let it commit to main. Or for security let it make a new branch and open a PR for it.

NLeSC / guide

Coding style for markdown files #119