> For the complete documentation index, see [llms.txt](https://capsbold.gitbook.io/guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://capsbold.gitbook.io/guide/html.md).

# HTML

> Вся информация основана на большом опыте и закреплена источниками: <https://html.spec.whatwg.org/> и <https://developer.mozilla.org/>, а также <https://docs.gitlab.com/ee/development/fe_guide/style/html.html>

## Семантическая вёрстка

[Семантические элементы](https://developer.mozilla.org/en-US/docs/Glossary/Semantics) - HTML-теги, которые придают семантическое (а не презентационное) значение содержащимся в них данным. Например:

* `<article>`
* `<nav>`
* `<strong>`
* `<aside>`

Лучше использовать семантические теги, но только в том случае, если намерение действительно соответствует семантическому значению самого тега. Посмотри [документацию MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element), чтобы узнать, что семантически означает каждый тег.

```html
<!-- плохо - можно использовать семантические теги вместо div. -->
<div class="...">
  <p>
    <!-- плохо - это не то, для чего предназначен тег strong -->
    Simply visit your <strong>Settings</strong> to say hello to the world.
  </p>
  <div class="...">...</div>
</div>

<!-- хорошо - предпочитаю семантические классы, используемые точно -->
<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>
```

## Кнопки

Теги кнопок требуют атрибута `type` в соответствии со [спецификацией W3C HTML](https://www.w3.org/TR/2011/WD-html5-20110525/the-button-element.html#dom-button-type).

```html
// плохо
<button></button>

// хорошо
<button type="button"></button>
```

## Ссылки

### \_blank

Не рекомендуется произвольно открывать ссылки в новой вкладке, поэтому при добавлении к ссылкам `target="_blank"`. Интересная статья по ссылкам: [Link Targets and 3.2.5](https://adrianroselli.com/2020/02/link-targets-and-3-2-5.html).

При использовании `target="_blank"` с тегами необходимо также добавить атрибут `rel="noopener noreferrer"`. Это предотвращает уязвимость безопасности, [задокументированную JitBit](https://www.jitbit.com/alexblog/256-targetblank---the-most-underestimated-vulnerability-ever/).

```html
// плохо
<a href="url" target="_blank"></a>

// хорошо
<a href="url" target="_blank" rel="noopener noreferrer"></a>
```

### Фейковые ссылки

Не используйте поддельные ссылки. Если ссылка вызывает только обработчики событий кликов JavaScript, то используйте тег кнопки. Это будет семантично.

```html
// плохо
<a class="js-do-something" href="#"></a>

// хорошо
<button class="js-do-something" type="button"></button>
```

## Атрибут Role

Не используйте role. Вместо этого используйте семантические элементы HTML, которые итак играют определенную роль.

## Комментарии

Всегда используй закрывающие комментарии для блочных НЕ семантических элементов. С этим прекрасно помогает плагин Emmet и настройка "auto\_comment".

Благодаря таким закрывающим комментарием, проще изучать и поддерживать вёрстку.

```html
// плохо
<div class="user">
    <div class="user__avatar">
        <img src="avatar.png" alt="">
    </div>
    <div class="user__info">
        <span>Василий</span>
        <span>vasya@mail.ru</span>
    </div>
</div>

// тоже плохо, так как aside - семантический тег
<aside class="sidebar">
    <!-- какой-то контент -->
</aside>
<!-- /.sidebar -->

// хорошо
<div class="user">
    <div class="user__avatar">
        <img src="avatar.png" alt="Василий">
    </div>
    <!-- /.user__avatar -->

    <div class="user__info">
        <span>Василий</span>
        <span>vasya@mail.ru</span>
    </div>
    <!-- /.user__info -->
</div>
<!-- /.user -->
```

## БЭМ

Использование БЭМ у нас - обязательное условие!

**В именовании классов не используйте бизнес-логику!** Вы должны называть элементы так, как их принято называть на английском языке по прямому назначению.&#x20;

Например:

* `.field` - поле ввода
* `.upload` - поле загрузки файлов
* `.menu` - меню
* `.tabs` - вкладки
* `.table` - таблица

Блоки и элементы мы именуем как и принято в БЭМ. Модификаторы мы пишем через два тире (`.notify--success`).