Grow your CSS skills. Land your dream job.

Show Markup in CSS Comments

Published by Chris Coyier

Let's say you are creating a CSS file for a modular bit of a webpage. Perhaps you are the type that separates your CSS files into bits like header.css, sidebar.css, footer.css, etc. I just ran across an idea I thought was rather clever where you include the basic markup you will be styling as a comment at the top of your CSS file. For example, a sidebar.css file might look like:

   <div class="widget">
       <h5 class="widget-title">
   <!-- other widgets -->

aside { background-color: #ccc; }
aside .widget { background-color: white; padding: 10px; }
aside .widget h5 { border-bottom: 1px solid black; }
/* etc. */

This could be useful for yourself as you would have to do less flipping back and forth between where you are viewing markup and this CSS file. This is even more useful when:

  1. The markup is generated by JavaScript and harder to see anywhere else or,
  2. The CSS is specific to a plugin or third-party add-on

I got this idea from the CSS file from mediaelements.js, which I think is a perfect use case example.


  1. Permalink to comment#

    Wouldn’t it cause a lot of maintenance overhead – to update the comment when the real html is updated, add other instances when that css portion is used…

    Now, if you could build a tool that does that tracing back from the CSS to the html within the CSS editor, this would be something I’d like to use :-)

    • I’m sure if there was a tool that did it automatically, people would then whine about the overhead.

      Yes, this would require maintenance. If it doesn’t make it easier for yourself or for the people you are providing the code to, don’t do it.

    • Permalink to comment#

      well, the tool can just add that html code as a tooltip for the css code, then it won’t bother people too much…

      I think that this idea is good, just makes the code less scalable and less sharable with others. I remember something that one of lecturers told me, that bad / misleading comment is worse then no comment at all. Once you scale up / share your code, it is easy to get to a place when you have bad comments.

  2. Permalink to comment#

    Interetsing idea, but if you use it all over your CSS and then change your markup you then have to change the comment as well, effectively doubling your work.

    • I’m not sure if copying/pasting really “doubles” your work. But on small personal projects that you can’t dedicate a lot of time/day to, this makes jumping back into things a lot easier.

  3. Thank you for the RT button, Chris

  4. Interesting and simple idea, i agree with Angelo, this idea makes things easier and i think it helps to make the css from scratch with no errors.

  5. Good idea. I am using split views in Coda so i don’t have to go back and forth and it’s really a time saver once you get used to open files that way.

  6. Interesting concept, but shouldn’t you order your CSS according to the HTML anyway? Plus consistent naming of ids and classes will help to “guess” the selectors.

  7. Really, all you would need to remember in that example is:

    You don’t need to class the h5 as you can hook into it from the cascade:

    aside .widget h5 {
    stuff here

    Your other widgets would ideally be the same or perhaps extended with something like:

    Comments in CSS are for delineating sections, browser hacks/workrounds/WTF is this, not markup.

  8. Permalink to comment#

    I like that idea, not sure how much code bloat it will add, but used in moderation I think it’s great

  9. Permalink to comment#

    I have inherited this sort of thing on a massive corporate site and I thought it would be a useful tool to know what I was working on but I’d have so say that while it’s useful in theory, it’s sadly not that practical in a production environment.

    Still, I’d say it possibly does have some uses and like Chris said up top, if you don’t want to use it, don’t.

    • In a real production environment this has no bearing. It does help in the development environment, however. When you are tasked with working on random sections, adding comments like this really help the rest of the team and whoever inherits maintenance of your application.

      Note that in a real production environment, your CSS is minified right? That will strip all of the comments right out.

  10. Jorgen
    Permalink to comment#

    Adding mark up to a CSS file doesn’t exactly increase its readability. I’m also a firm believer that good code doesn’t require a lot of comments anyway. If you want to place a comment in your code you should first ask yourself if you can’t simplify the code instead of having to write an explanatory comment.

    • There are quite a few factors to this, lets say you know your code is going to be viewed by a lot of newbies and you want them to understand, then you would explain it, and having the HTML viewable right next to the CSS would be great to learn with.

      But I believe that comments do make it more readable, for me, I comment my blocks of CSS so it’s easier to find which CSS code styles which part of the markup.

      But what you say is right, if its possible do try to make it as simple as possible.

  11. Permalink to comment#

    That’s a good idea, but I think it might be usefull only for very very very specific works. Specially the smaller ones. Too much complex markup structures could cause a misunderstood of architetural info. Even for a single developer. It could be useful for teaching as well. Tks for share!

  12. Got to say I never really thought of that, awesome idea, it does get quite irritating have to to flick back and forth between HTML & CSS.

  13. I am actually not sure if I think this is a good idea or bad. I can’t think of a time for me personally where that would be more appropriate than just putting a comment that says “This is the styles for nav” or something like that.

  14. Chris,

    I have a number of CSS templates (i.e. screen, nav, print, forms, etc.) that contain very basic rules that I often re-use for various client projects so adding the markup would prove very useful as code snippets that too could be re-purposed in the actual HTML files(s).

    Thanks for the tip.


  15. Permalink to comment#

    Oh Chris, awesome idea.
    I usually tend to use one CSS file, however I do heavily comment it.
    And I do find myself switching back and forth ALL the time, so I’m glad you brought this idea to my attention.

    Thanks again!

  16. WC
    Permalink to comment#

    While I wouldn’t use this everywhere, I can see certain circumstances that would really be nice for this. If you’re compiling your CSS down anyhow (with Sass/Compass?) then this is even better.

    Thanks for posting this!

  17. David
    Permalink to comment#

    The CSS File get larger and larger. If you got big websites with mass css your loading time would be longer or? Many People say you should wirte short css and compress it. I dont know whats better. Its nice to see what is what.

  18. I like the idea! Just before scrolling down to Comments, I thought, ‘Somebody’s going to complain about file size’ ; sure enough! But as you say, in places, selectively, it could be good. Thanks!

  19. Permalink to comment#

    This is a great idea, I’ve been doing it for about a year now. As long as you compress your CSS, all comments are stripped out anyway, so it really helps for dev (and helps a LOT I might add).

  20. Anthony
    Permalink to comment#

    I love the readability of this idea!

    I’ve always read and been told that it’s better to use just one stylesheet and so that’s the way I’ve always approached my CSS.

    I do get tired sometimes of scrolling through a long stylesheet to find particular parts (even with comments). Where this approach might cause a little extra work in one place it could save you time in another.

    With a little extra (reusable) work, you could easily code your CSS like this and have it all pulled together into a single stylesheet with something like PHP…I think? I’m still fairly new at this but at least it works in my imagination. Could be something cool to try :)

  21. Permalink to comment#

    I do this (similar idea):

    body{ width: 100%; margin: 0; etc: etc; }
    #container{ width: 80%; min-width: 600px; margin: 0 auto; etc: etc; }
    #banner{ width: 100%; height: 145px; background: 'neausea green'; etc: etc; }
    #banner h1{ font-family: 'palatino linotype', serif; color: 'sky blue'; }
    #banner p{ padding: 1.5em; etc: etc; }
    .column{ width: 30%; margin: 2em; display: inline; etc: etc; }
    .column a{ color: orange; }

    • Permalink to comment#

      (Well, I had it all indented to reflect the hierarchy of the markup, but I guess the <pre> tag doesn’t remind WordPress to preserve the extra whitespace…!)


  22. Permalink to comment#

    If you work on larger scale applications and create styles that work like Legos and that many many developers end up using, this is something you HAVE to do. It can essentially serve as documentation right in the file. Together, with a table of contents, you’ll be able to make friends with hardcore developers who get the same kind of commenting they expect in their hardcore programming files. And who doesn’t want to do that? Just make sure you use a solution that strips the comments before you push it live.

  23. Permalink to comment#

    What about reversing this idea? I think it would be better to add CSS markup in HTML comments and then collect them with some kind of script. Example:

    In this case all CSS and HTML markup will be in the same file :)

  24. Interesting idea. I guess it would work in certain cases. It’s always nice to comment CSS to make it a bit easier to understand and maintain. :-)

  25. Will
    Permalink to comment#

    I like the idea a lot and can see it making my work easier. Nice one!

  26. Permalink to comment#

    im filing this in my “obvious” folder

  27. Permalink to comment#

    does W3C allows the “aside” elements so it will still W3C Valid HTML ?

  28. Permalink to comment#

    Wow i never thought it can be done that way,thank for new things that i didn’t know

  29. Permalink to comment#

    Thanks, another idea I may use in the future. LT

  30. Euan Mead
    Permalink to comment#

    Why wouldn’t you put the CSS in your HTML document (WordPresss Header)? Simpler. Then once it is designed cut and paste it into a new stylesheet.

  31. Message Corp takes text messaging to a new level.
    Our interactive text messaging makes it possible to engage
    in a highly personalized and fully-automated customer dialog.
    As a result, customers can access product inquiries,authorize
    payments, and confirm transactions – conveniently from their
    mobile phone and without the assistance of an agent.And for
    those customer interactions that require special handling,
    we make it possible for your agents to seamlessly interact
    with your customers via text.

This comment thread is closed. If you have important information to share, you can always contact me.

*May or may not contain any actual "CSS" or "Tricks".