GitHub のハイライトがおかしい時のなおしかた（GitHub のハイライトの仕組み）

GitHub

GitHub でコードを見ていると，ハイライトがおかしいのを見つけることがたまにあります．ここではその直し方を紹介します．

次の2パターンを想定しています．

  • 自分のリポジトリのあるファイルのハイライト言語がおかしい
  • 構文ハイライトが間違えている，言語の新機能に対応していない

自分のリポジトリのあるファイルのハイライト言語がおかしい

コードをどの言語でハイライトするかは自動判別されますが，実はある程度ユーザ側で制御する方法があります．

Vim や Emacs のモードラインを書く

ファイル単位で Vim や Emacs の設定をマジックコメントとして書けるモードラインですが，実は GitHub もそれを参照しています

// C++ だけど拡張子は .h … C じゃなくて C++ でハイライトしてほしい

// vim: set ft=cpp
//
// または
//
// -*- mode: cpp;-*-

これで上記のコードは C++ として認識されるはずです．

.gitattributes に指定する

リポジトリの .gitattributes ファイルにハイライトを指定することもできます．

$ cat .gitattributes
*.h linguist-language=C++

またハイライト以外の設定もできて，

$ cat .gitattributes
vendor/* linguist-vendored
docs/*.rb linguist-documentation=false

例えば上記の設定をすると，vendor/ 配下は他のプロジェクトのコードと判断してリポジトリの stat （リポジトリページのヘッダにあるコード率など）から除外できたり，docs/*.rb はドキュメント向けのコードとして，stat カウントから除外できたりします．

構文ハイライトが間違えている，言語の新機能に対応していない

実は GitHub のコードハイライトを行うライブラリは OSS で公開されています．

https://github.com/github/linguist

このリポジトリでは

など様々なメタデータが管理されています．なので例えば新しい言語をつくって十分に普及してきたら，ここに自分の言語を追加したプルリクを出すなどもできるわけですね．

今回は一番最後の言語のハイライト方法を見ます．

GitHub のハイライトは .tmbundle という，TextMate の構文ハイライトフォーマットまたは，Atom の cson を使った構文ハイライトフォーマットを利用してハイライトされています．これらはオープンソースで開発されているものを利用しており，一覧は下記のディレクトリにあります．

https://github.com/github/linguist/tree/master/vendor/grammars

サブモジュールでリビジョン固定されていますが，何らかのタイミングで更新されているので，対象の .tmbundle や .cson を管理しているリポジトリにプルリクを投げて修正してもらえばいずれ linguist の依存する構文ハイライターもアップデートされ，GitHub 上のハイライトがなおるという仕組みです．

例えば僕は以前 Vim script の try ... finally がハイライトされていないことに気づいたので，それを追加するプルリクを投げました．

また，上記リポジトリでは各種フレームワーク対応（例えば jquery.*.js は jQuery のファイルなど）も行われているので，各フレームワーク向けのハイライトを改善したい時は YAML の設定ファイル にプルリクを出せば良さそうです．

GitHub でコードを読んでいるとハイライトが壊れていて困ることがあるかもしれませんが，実は自力で修正できますというご紹介でした．

公式ドキュメント

https://github.com/github/linguist/blob/master/docs/overrides.md