markdown guide

Aside from the stuff linters pick up:

  • Avoid unnecessary divs and spans, try to put content into the appropriately-semantic containers.
  • Only one opening or closing tag per line
  • Indent nested tags consistently (2 spaces is my preference, but that's all it is - a preference)
  • Use one line break as vertical whitespace between containing blocks.
  • Use one line break as vertical whitespace between unrelated meta tags, scripts, stylesheets, etc.

And I try to write it while keeping in mind that it's not necessarily going to be the only output format.


Reading the Google Style Guide for HTML/CSS really helped me a lot. Like all dogma, it's probably best to take it with a grain of salt :-)


Great starting point. But somehow in working in large team always leaves HTML messy. :(


Is it more true for HTML than, for example, CSS or JavaScript?

It's definitely a good point! We should be considering our HTML templates in our refactoring efforts as well.


Yes! That was news to me too. I made one page that way just to confirm, but generally avoid it since most linting tools will complain, and on some level it just never felt right to leave out the closing tag...

Yeah and also I'm sure some browser will complain ๐Ÿคฃ๐Ÿคฃ


I'm still recovering from the ill-fated XHTML era.

Leaving off the HTML5 optional closing tags will take some getting used to.

But I've gotten used to (and now, I even prefer) leaving off the semicolon in JavaScript when it is superfluous, I'm sure I can do the same in the HTML context.


I use Tidy for HTML, and Standard for JavaScript.

(I was a contributor to Dave Raggett's Tidy, in its early early days.)


Is there a plugin for Tidy too? Could we use it with vscode?


Looks like there is VSCode-Tidy, which is for the current version of Tidy (HTML5).


Itโ€™s completely arbitrary for me since I find HTML to be very inelegant. Thus I just try to make it not look cluttered like many webpages do. AngularJS helps a lot with this.


I am always confused as to if we should write as small code as possible or write more nested HTML?


I think you should try to write as much HTML as the semantic structure requires, and arrange it in such a way that another human will be able to understand and edit it. You're writing declarative code for:

  • browsers,
  • assistive technology, and
  • things like search bots

that all need to know the document's structure and how best to help users find what they're looking for (or help complete some action). It's possible to write too little HTML and miss the mark on conveying the meaning and structure of the content, and it's possible to write too much HTML in an effort to give yourself containers that can be styled for visual effects (but this is often easily avoided).

HTML should primarily focus on conveying that clearly enough that in the absence of CSS and JavaScript, you'd be able to scan the page and recognize it as a readable document with a hierarchy.

(This could be as simple as using headings appropriately; using lists for lists, rather than using something else with CSS counters, which seems sexy; using tables for tabular data; and using articles for syndicated content like blog posts.)

Back to the people who will be looking at and possibly editing your HTML, you should be consistent and nest children below their parents. For example, siblings should sit beside one another under their common parent, at the same level of indentation, so that the next editor can easily see the relationship. And so on.

I like to use two spaces for each successive level, and that seems the most standard approach. It's probably because using 4 spaces or tabs can make it much harder to read the deeper you go. 2 spaces seems just right.

Ben's comment seems pretty right on to me, but I wanted to give some special emphasis to the need to write for both technology and for people.

Classic DEV Post from Feb 9

What do you have to Google? Every. Single. Time.

How about you? Any other stories to make me feel better?

Akanksha Sharma profile image
Javascript Dev , Hobbit of The Shire