GitHub README에 ASCII 배너 넣는 법

프로젝트 이름을 ASCII 배너로 넣으면 README 첫 화면이 눈에 띄어요. 이미지와 달리 글자라서 용량이 없고, 밝은 테마와 어두운 테마 모두에서 자연스럽게 보입니다.

README에 넣기

마크다운에서는 코드 블록 안에 넣어야 해요. 코드 블록 밖에서는 연속된 공백이 하나로 합쳐지고 _ 나 * 가 기울임·굵게 표시로 바뀌어서 그림이 깨집니다.

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

# my-project

터미널에서 바로 쓰는 작은 CLI 도구입니다.

• 여는 백틱 뒤에 text 를 적으면 문법 강조가 적용되지 않아서 글자 색이 섞이지 않아요.
• 배너 아래에 글자로 된 제목(# my-project)을 따로 넣으세요. 검색 엔진과 화면 낭독기는 배너를 프로젝트 이름으로 읽지 못해요.
• 그림 안에 백틱 세 개가 연달아 있으면 바깥을 백틱 네 개로 감싸세요.

폭은 80자 이하로

GitHub의 코드 블록은 줄이 길면 가로 스크롤이 생겨요. 배너가 잘려 보이면 의미가 없으니 80자 이하, 휴대폰에서도 보이게 하려면 50자 안팎이 좋아요.

볼 곳	권장 폭
GitHub README (PC)	80자 이하
GitHub 모바일 앱·좁은 화면	50자 안팎
터미널 출력	80자 이하

프로젝트 이름이 길면 Standard나 Big 대신 Small, Mini 같은 작은 글꼴을 고르거나 이름을 두 줄로 나누세요. lab.ascii의 글꼴 카드 오른쪽 위에 결과의 폭이 표시됩니다.

코드 주석에 넣기

파일 맨 위나 큰 구역의 시작을 배너로 표시하면 긴 파일에서 위치를 찾기 쉬워요.

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

• 줄마다 주석 기호(*, //, #)를 붙이세요.
• 그림에 */ 가 들어 있으면 블록 주석이 거기서 끝나요. 그런 그림은 // 줄 주석으로 넣으세요.
• 팀에서 줄 길이 제한(예: 100자)을 쓰고 있다면 그 안에 들어오는 폭으로 만드세요.

프로그램 시작 화면에 넣기

CLI 도구를 실행했을 때 배너를 출력하려면 그림을 문자열로 넣어야 해요. 이때 역슬래시(\) 가 문제입니다. 대부분의 언어에서 역슬래시는 특수 문자를 시작하는 기호라서, 그대로 넣으면 글자가 사라지거나 오류가 나요.

자바스크립트에서는 String.raw 를 쓰면 역슬래시를 그대로 둘 수 있어요.

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

그림에 백틱이나 ${ 가 들어 있으면 템플릿 문자열이 끊기니, 그런 그림은 다른 글꼴로 바꾸는 편이 쉬워요.

파이썬에서는 문자열 앞에 r 을 붙인 원시 문자열을 쓰세요.

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

시작 화면 배너는 다음 두 가지를 지키면 쓰는 사람이 불편하지 않아요.

• 출력이 다른 프로그램으로 넘어갈 때(파이프, 로그 파일)는 배너를 찍지 않기
• --quiet 같은 옵션으로 끌 수 있게 하기

어떤 글꼴이 좋은가요?

글꼴	특징
Standard	가장 무난해요. 어떤 이름에도 어울려요
Slant	기울어진 모양. 속도감이 있어요
Small	Standard의 작은 판. 긴 이름에 좋아요
ANSI Shadow	블록 문자로 꽉 찬 굵은 글자. 눈에 가장 잘 띄어요
Calvin S	세 줄짜리 작은 글자. 코드 주석에 좋아요

ANSI Shadow와 Calvin S는 ASCII 밖의 선·블록 문자(█ ╗ ═)를 써요. GitHub과 대부분의 터미널에서는 잘 보이지만, 아주 오래된 환경에서는 깨질 수 있습니다. 어디서나 보여야 한다면 Standard, Slant, Small처럼 ASCII 문자만 쓰는 글꼴을 고르세요.

lab.ascii에 프로젝트 이름을 입력하면 12가지 글꼴의 배너를 한 번에 비교하고, 카드를 눌러 바로 복사할 수 있어요.