GitHub Styleguide を訳してみた（HTML & Templates編）

GitHubによるコーディングスタイルガイドのうち、マークアップやテンプレート（エラーページ）に関わるものを翻訳してみました。原文は[こちら](https://github.com/styleguide/templates)にあります。

そのうちRuby編やJavaScript編にも手を付けていこうと思います。


**追記**

[Ruby編](http://qiita.com/edwardkenfox/items/33bfadd5fe7c10b9acc5)を作りました。

---

# 0.マークアップとテンプレート

## Doctype 宣言

ブラウザが標準モードをトリガするように、適切なdoctypeを使う必要があります。互換モードは常に避けるべきです。

簡単のために、私たちは`html5` doctypeを使います。

```html
<!DOCTYPE html>
```

## コーディングスタイル

### 汎用的なフォーマット

- 文章における段落は、常に`<p>`タグを使います。`<br>`タグを複数使ってはいけません。
- リスト形式の要素は常に`<ul>`、`<ol>`もしくは`<dl>`を使います。`<div>`や`<p>`を組み合わせて使ってはいけません。
- 入力フォームに文章が付随する場合、**特にラジオボタンやチェックボックス要素において**は`<label>`タグを使います。
- タグの属性はクォートで囲まずに記述することができますが、可読性のために属性をクォートで必ず囲みます。
- `<!-- /.element -->`のように、閉じタグにコメントで目印をつけるのは避けましょう。ページのロード時間が増えるだけですし、ほとんどのエディタにはインデントガイドや開始／閉じタグのハイライト機能がついているからです。
- `<br>`、`<hr>`、`<img>`や<input>など、空要素のタグにスラッシュをつけることは避けます。
- `tabindex`を記述するのは避け、順序の設定はブラウザに依拠するようにします。

```html
<p class="line-note" data-attribute="106">This is my paragraph of special text.</p>
```

### ブール値属性

多くの属性においては、`disabled`や`checked`などの値が設定は必須ではないので、設定はしないようにしましょう。

```html
<input type="text" disabled>

<input type="checkbox" value="1" checked>

<select>
  <option value="1" selected>1</option>
</select>
```

より詳しい情報については[WhatWG section](https://html.spec.whatwg.org/multipage/infrastructure.html#boolean-attributes)を参照してください。

### リーンなマークアップ

HTMLを書くときは、余計な親要素は出来るかぎり使わないようにします。繰り返しの作業やリファクタリングを必要とする反面、出力するHTMLは少なくなります。以下がその例です。

```html
<!-- 悪い -->
<span class="avatar">
  <img src="...">
</span>

<!-- 良い -->
<img class="avatar" src="...">
```

### フォーム

- セレクトボックスよりも、ラジオボタンやチェックボックスを使う方が好ましいです。
- ラジオボタンやチェックボックスは、それぞれ`<label>`で囲みます。`for`属性がなくても、囲まれた要素は自動的にひも付きます。
- フォームのボタンは常に`type`属性をもつべきです。プライマリなボタン（もっとも重要なボタン）を`type="submit"`とし、ほかのボタンは`type="button"`としましょう。
- 特に複数の送信ボタンが存在するフォームにおいては、プライマリなボタンがDOM構造の最初に来るようにします。各ボタンの表示上の順序は`float: right;`によって維持します。

### テーブル

`<thead>`、`<tfoot>`、`<tbody>`や`<th>`タグ（と`scope`属性）を適切な箇所で使います。（`<tfoot>`が`<tbody>`より先に来ていることに注意しましょう。ブラウザにデータが入った表を読み込ませる前にフッターをロードさせるためです。）

```html
<table summary="2011年請求書一覧">
  <thead>
    <tr>
      <th scope="col">表ヘッダー 1</th>
      <th scope="col">表ヘッダー 2</th>
    </tr>
  </thead>
  <tfoot>
    <tr>
      <td>表フッター 1</td>
      <td>表フッター 2</td>
    </tr>
  </tfoot>
  <tbody>
    <tr>
      <td>表データ 1</td>
      <td>表データ 2</td>
    </tr>
  </tbody>
</table>
```

# 1. ページタイトル

GitHubのページには基準となる`<title></title>`が存在します。サインアウトした状態のページには`.GitHub`が最後に付きます。サインインしたユーザからはGitHubは消えます。

## 一般的なページ

ほとんどのページでは以下のフォーマットに沿います。

```
THING ・ WHO ・ GitHub
```

例：`Pull Requests ・ rails/rails ・ GitHub`

## プロフィールページ

プロフィールページでは、デベロッパーが`USERNAME`と`FULL NAME`を設定している場合、それらを含みます。

```
USERNAME (FULL NAME) ・ GitHub
```

例：`jonrohan (Jon Rohan) ・ GitHub`

## リポジトリページ

リポジトリのページでは、そのリポジトリの`OWNER`と`REPOSITORY`のタイトルを含みます。

```
OWNER/REPOSITORY ・ GitHub
```

例：`twitter/bootstrap ・ GitHub`

# 2.エラーページ

エラーページは、スクリプトやJavaScriptなどを一切使わず、またどんな依存ももたないように構築されているべきです。つまり、静的なHTMLとインラインのCSS、そしてbase64エンコードの画像のみで作られているべきです。

以下の要素はどのエラーページにおいても使用が禁じられています：

- `src`属性をもった`<script>`タグ
- 外部データをロードするJavaScript
- `<link>`タグ
- `src`がURLを指す`<img>`タグ

## テンプレートリスト

個別の目的に沿ったテンプレートページを複数用意しています。

- **[500](https://github.com/500.html)** – 例外が発生しリカバリできなかった

- **[502](https://github.com/502.html)** – ユニコーン! ページがタイムアウトになった

- **[503](https://github.com/503.html)** – ユニコーン! 問題が発生しアプリケーションサーバと通信ができない

- **[404](https://github.com/404.html)** – Not found

- **[404(Pages)](https://github.com/404-pages.html)** – [Pages](http://pages.github.com/) 用のNot found

- **[410](https://github.com/410-feature.html)** – 削除された機能

- **[422](https://github.com/422.html)** –  リクエストに対してNginxがレスポンスできないとき

- **[maintenance](https://github.com/maintenance.html)** – メンテナンスを行うためにウェブサイトを落としているとき

## ところで

[Repro株式会社](https://repro.io/)では一緒に切磋琢磨できる仲間を募集しています。 ぜひ[こちら](https://www.wantedly.com/companies/repro/projects)をごらんください！