如何在 GitHub README 中加入 ASCII 字符画横幅

把项目名做成 ASCII 横幅，README 的开头会格外醒目。和图片不同，它只是纯文本，不会给仓库增加文件，在浅色和深色主题下都好看。

加到 README 中

在 Markdown 中，横幅必须放在代码块里。放在外面的话，连续的空格会被合并成一个，_ 和 * 也会变成斜体和粗体标记，字符画就毁了。

```text
                                       _           _
 _ __ ___  _   _       _ __  _ __ ___ (_) ___  ___| |_
| '_ ` _ \| | | |_____| '_ \| '__/ _ \| |/ _ \/ __| __|
| | | | | | |_| |_____| |_) | | | (_) | |  __/ (__| |_
|_| |_| |_|\__, |     | .__/|_|  \___// |\___|\___|\__|
           |___/      |_|           |__/
```

# my-project

一个可以直接在终端运行的小 CLI 工具。

• 在开头的反引号后写上 text，可以关闭语法高亮，让字符保持单一颜色。
• 在横幅下方加上真正的文字标题（# my-project）。搜索引擎和读屏软件无法把横幅识别为项目名。
• 如果字符画中连续出现三个反引号，请改用四个反引号包起来。

控制在 80 列以内

GitHub 的代码块在行太长时会横向滚动。被截断的横幅就失去了意义，所以请控制在 80 列以内；如果也想在手机上完整显示，就控制在 50 列左右。

阅读的地方	建议宽度
电脑上的 GitHub README	最多 80 列
GitHub 移动应用、窄屏	约 50 列
终端输出	最多 80 列

项目名较长时，请选择 Small、Mini 等较小的字体代替 Standard 或 Big，或者把名字分成两行。lab.ascii 每张字体卡片的右上角都会显示结果的宽度。

加到代码注释中

在文件开头或大段代码的开头放一个横幅，长文件里也更容易找到位置。

/*
 *  ___ ___ _  _ ___  ___ ___
 * | _ \ __| \| |   \| __| _ \
 * |   / _|| .` | |) | _||   /
 * |_|_\___|_|\_|___/|___|_|_\
 */
export function render() {}

• 每一行都以注释符号（*、// 或 #）开头。
• 如果字符画中有 */，块注释会在那里结束。这样的字符画请使用 // 行注释。
• 如果团队规定了每行的长度（例如 100 个字符），请让横幅控制在范围内。

在程序启动时打印

想在 CLI 工具启动时打印横幅，就需要把字符画存为字符串。问题在于反斜杠（\）。在大多数语言中，反斜杠是转义序列的开头，直接粘贴字符画会丢字符或报错。

在 JavaScript 中，String.raw 可以原样保留反斜杠。

const banner = String.raw`
 _  _ ___ _    _    ___
| || | __| |  | |  / _ \
| __ | _|| |__| |_| (_) |
|_||_|___|____|____\___/
`;
console.log(banner);

字符画中如果有反引号或 ${，模板字符串会在那里结束。这种字符画通常换一种字体更省事。

在 Python 中，在字符串前加 r，使用原始字符串。

BANNER = r"""
 _  _ ___ _    _    ___
| || | __| |  | |  / _ \
| __ | _|| |__| |_| (_) |
|_||_|___|____|____\___/
"""
print(BANNER)

启动横幅只要遵守两条规则，就不会碍事。

• 输出交给其他程序时（例如管道或日志文件），不要打印。
• 提供 --quiet 之类的选项来关闭它。

用哪种字体好？

字体	特点
Standard	稳妥的默认选择，适合任何名字
Slant	带速度感的斜体字母
Small	缩小版的 Standard，适合较长的名字
Banner	用 # 填满的粗大字母，最醒目
Digital	每个字母装在方框里的 3 行小横幅，适合代码注释

lab.ascii 的 12 种字体都只使用 ASCII 字符，在 GitHub、终端和旧环境中都不会乱。其他生成器用方块字符（█ ╗ ═）做的横幅，在非常旧的环境中可能会乱，所以如果横幅必须到处可用，请选择 ASCII 字体。

在 lab.ascii 输入项目名，就能比较 12 种字体的横幅，点击卡片即可复制。