HTML style guide
See also our accessibility best practices.
Semantic elements
Semantic elements are HTML tags that give semantic (rather than presentational) meaning to the data they contain. For example:
Prefer using semantic tags, but only if the intention is truly accurate with the semantic meaning of the tag itself. View the MDN documentation for a description on what each tag semantically means.
<!-- bad - could use semantic tags instead of div's. -->
<div class="...">
<p>
<!-- bad - this isn't what "strong" is meant for. -->
Simply visit your <strong>Settings</strong> to say hello to the world.
</p>
<div class="...">...</div>
</div>
<!-- good - prefer semantic classes used accurately -->
<section class="...">
<p>
Simply visit your <span class="gl-font-bold">Settings</span> to say hello to the world.
</p>
<footer class="...">...</footer>
</section>
Buttons
Button type
Button tags requires a type
attribute according to the W3C HTML specification.
// bad
<button></button>
// good
<button type="button"></button>
Links
Blank target
Arbitrarily opening links in a new tab is not recommended, so refer to the Pajamas guidelines on links when considering adding target="_blank"
to links.
When using target="_blank"
with a
tags, you must also add the rel="noopener noreferrer"
attribute. This prevents a security vulnerability documented by JitBit.
When using gl-link
, using target="_blank"
is sufficient as it automatically adds rel="noopener noreferrer"
to the link.
// bad
<a href="url" target="_blank"></a>
// good
<a href="url" target="_blank" rel="noopener noreferrer"></a>
// good
<gl-link href="url" target="_blank"></gl-link>
Fake links
Do not use fake links. Use a button tag if a link only invokes JavaScript click event handlers, which is more semantic.
// bad
<a class="js-do-something" href="#"></a>
// good
<button class="js-do-something" type="button"></button>
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support