2.8 KiB
| stage | group | info |
|---|---|---|
| none | unassigned | To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments |
HTML style guide
See also our accessibility page.
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-weight-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>