I use Markdown-inspired headings in my CSS comments, to structure my code and make it easier to parse visually and maintain. I tend to use two, sometimes three levels of headings.

For the first two levels, I use a rather verbose syntax. But it’s not too hard to type (especially in the SCSS syntax), and it makes it easier to spot the different headings.

Is it a good style? I don’t know. I’ve only ever used it in my personal projects. But I like it, so I’m sharing it.

/* ================= */
/* LEVEL ONE HEADING */
/* ================= */

/* ----------------- */
/* Level two heading */
/* ----------------- */

/* ### Level three heading ### */
/* Additional information goes here. */

And in SCSS:

// =================
// LEVEL ONE HEADING
// =================

// -----------------
// Level two heading
// -----------------

// ### Level three heading ###
// Additional information goes here.

Differences from Markdown

I’m not using strict Markdown in the heading-comment style above. The main differences are:

  • The top lines of equals (=====) and hyphens (-----) are not part of the Markdown syntax for headings. I use them because I feel it makes the headings more visible and visually balanced, but processed as Markdown they would produce <p>=====</p> and <hr />, respectively.

  • I’m using uppercase letters for the top level heading-comment, which is an arbitrary style decision.