GitHub README にアスキーアートのバナーを入れる方法
Markdown のコードブロックに入れて、80列以内に収めましょう。
プロジェクト名をアスキーアートのバナーにすると、README の冒頭が目を引きます。画像と違ってただのテキストなので、リポジトリにファイルが増えず、ライトテーマでもダークテーマでもきれいに見えます。
README に入れる
Markdown では、バナーをコードブロックの中に入れる必要があります。外に置くと連続したスペースが1つにまとめられ、_ や * が斜体や太字の記号に変わって、アートが崩れてしまいます。
```text
_ _
_ __ ___ _ _ _ __ _ __ ___ (_) ___ ___| |_
| '_ ` _ \| | | |_____| '_ \| '__/ _ \| |/ _ \/ __| __|
| | | | | | |_| |_____| |_) | | | (_) | | __/ (__| |_
|_| |_| |_|\__, | | .__/|_| \___// |\___|\___|\__|
|___/ |_| |__/
```
# my-project
ターミナルからすぐに使える小さな CLI ツールです。
- 最初のバッククォートのあとに
textと書くと、シンタックスハイライトがオフになり、文字が1色のままになります。 - バナーの下に**本物のテキストの見出し（
# my-project）**を入れてください。検索エンジンやスクリーンリーダーは、バナーをプロジェクト名として読めません。 - アートの中にバッククォートが3つ並んでいる場合は、4つのバッククォートで囲みます。
80列以内に収める
GitHub のコードブロックは、行が長すぎると横にスクロールします。途中で切れたバナーでは意味がないので、80列以内、スマホにも収めたいなら50列くらいにしましょう。
| 読まれる場所 | おすすめの幅 |
|---|---|
| パソコンで見る GitHub README | 80列まで |
| GitHub のモバイルアプリ、狭い画面 | 約50列 |
| ターミナルの出力 | 80列まで |
プロジェクト名が長いときは、Standard や Big の代わりに Small や Mini のような小さいフォントを選ぶか、名前を2行に分けてください。lab.ascii のフォントカードの右上に、結果の幅が表示されます。
コードのコメントに入れる
ファイルの冒頭や大きなセクションの始まりにバナーを置くと、長いファイルの中でも今いる場所がわかりやすくなります。
/*
* ___ ___ _ _ ___ ___ ___
* | _ \ __| \| | \| __| _ \
* | / _|| .` | |) | _|| /
* |_|_\___|_|\_|___/|___|_|_\
*/
export function render() {}
- すべての行をコメント記号（
*、//、#）で始めます。 - アートの中に
*/があると、ブロックコメントがそこで終わります。そのアートには//の行コメントを使ってください。 - チームで1行の長さ（100文字など）を決めている場合は、その中に収まるようにします。
プログラムの起動時に表示する
CLI ツールの起動時にバナーを表示するには、アートを文字列として持つ必要があります。問題は**バックスラッシュ（\）**です。ほとんどの言語ではバックスラッシュがエスケープシーケンスの始まりになるので、アートをそのまま貼ると文字が抜けたりエラーになったりします。
JavaScript では、String.raw を使うとバックスラッシュがそのまま残ります。
const banner = String.raw`
_ _ ___ _ _ ___
| || | __| | | | / _ \
| __ | _|| |__| |_| (_) |
|_||_|___|____|____\___/
`;
console.log(banner);
アートの中にバッククォートや ${ があると、テンプレート文字列がそこで終わります。そのアートは別のフォントに替えるほうが簡単です。
Python では、前に r を付けて raw 文字列にします。
BANNER = r"""
_ _ ___ _ _ ___
| || | __| | | | / _ \
| __ | _|| |__| |_| (_) |
|_||_|___|____|____\___/
"""
print(BANNER)
起動時のバナーは、次の2つを守れば邪魔になりません。
- 出力がパイプやログファイルなど別のプログラムに渡るときは表示しない。
--quietのような、オフにするオプションを用意する。
どのフォントを使えばいい？
| フォント | 特徴 |
|---|---|
| Standard | 無難な定番。どんな名前にも合う |
| Slant | スピード感のある斜めの文字 |
| Small | 小さな Standard。長い名前に向いている |
| Banner | # で埋めた太い文字。いちばん目立つ |
| Digital | 文字を箱に入れた3行の小さなバナー。コードのコメントに向いている |
lab.ascii の12種類のフォントはすべて ASCII の文字だけを使うので、GitHub やターミナル、古い環境でも崩れません。ほかの作成ツールでブロック文字（█ ╗ ═）を使ったバナーは、とても古い環境では崩れることがあります。どこでも動く必要があるなら、ASCII のフォントを選んでください。
lab.ascii でプロジェクト名を入力すると、12種類のフォントのバナーを比べて、カードをクリックするだけでコピーできます。