Why should I use code markers?

From the very beginning, an important part of writing style guide examples was to communicate to other developers: What’s important/different in this example? When styling with CSS class names only, while choosing the HTML tag doesn’t change the visual output, it helps to visualize this in the example by marking the parts, which style that current example:

<div class="user">
<h1 class="user--name">Homer Simpson</h1>
</div>

To make this work, ***…*** is used to set the markers—a bit like setting bold text in Markdown with **…**:

<div class="***user***">
<h1 class="***user--name***">Homer Simpson</h1>
</div>

So the example shown above would also work with the following code:

<h1 class="user">
<a href="#" class="user--name">Homer Simpson</a>
</h1>

Otherwise it should have been marked in yellow:

<div class="user">
<h1 class="user--name">Homer Simpson</h1>
</div>

Using other templating engines

This works well with every templating engine. Here’s how you add code markers to Haml

.user
%h1.user--name Homer Simpson
@haml
***.user***
%h1***.user--name*** Homer Simpson

Documenting the diffrence between examples:

For every example that only slightly changes to the previous one, just mark the changes:

<a class="my-button">Button</a>
<a class="my-button -primary">Button</a>
<a class="my-button -danger">Button</a>

Conclusion

I always try to write code that is easy to understand for people who are looking at it for the first time. Without code markers, the HTML examples—when used for more than a button–can get very complex. Code markers help people to find the important parts more easily.

So, happy marking the important parts of your examples :)

Update Apr 16, 2015

If you are interested how this has been implemented in Ruby: I wrote a follow-up post on RegExp and parsers.

gem install livingstyleguide