Quick Syntax

[링크 텍스트](https://example.com)
[링크 텍스트](https://example.com "툴팁 텍스트")

![대체 텍스트](https://example.com/image.png)
![프로세스 상태도](./images/process-state.png)

링크 text에는 목적지를, alt에는 이미지가 전달하는 정보를 씁니다. title은 보조 tooltip일 뿐 핵심 정보를 대신하지 못하며, 장식 이미지에만 빈 alt를 쓰고 기술 다이어그램·오류 화면의 핵심 내용은 주변 문장에도 남깁니다.

문법

링크 텍스트는 목적지를 설명해야 한다

링크의 [텍스트] 부분은 독자가 클릭 여부와 목적지를 판단하는 중요한 단서다. "여기 클릭", "이 링크", "자세히"처럼 맥락 없는 표현은 링크만 모아 읽는 화면이나 보조 기술에서 특히 뜻이 흐려진다. "PostgreSQL SELECT 문서", "설치 가이드", "변경 로그"처럼 목적지 내용을 담은 텍스트를 쓴다.

<!-- 나쁜 예 -->
자세한 내용은 [여기](https://example.com)를 참고하세요.

<!-- 좋은 예 -->
자세한 내용은 [PostgreSQL SELECT 문서](https://www.postgresql.org/docs/current/tutorial-select.html)를 참고하세요.

이미지의 대체 텍스트(alt)는 이미지가 없어도 의미가 전달되게 작성해야 한다

이미지 문법 ![alt](url) 에서 alt 텍스트는 이미지가 로드되지 않을 때와 보조 기술이 이미지를 설명할 때 쓰인다. 빈 alt(![])는 이미지가 장식적이거나 이미 인접 텍스트로 충분히 설명됐다는 선택에 맞춰 쓴다. 내용 전달 목적이 있는 이미지에 빈 alt를 두면 중요한 정보가 빠질 수 있다. alt 텍스트는 "이미지를 보지 않아도 같은 정보를 얻을 수 있는가"를 기준으로 작성한다.

<!-- 나쁜 예: 의미 없는 alt -->
![image](./diagram.png)

<!-- 좋은 예: 내용을 설명하는 alt -->
![HTTP 요청-응답 사이클 다이어그램](./images/http-cycle.png)

이미지는 보조 자료여야 하며 핵심 설명을 이미지에만 담으면 안 된다

이미지로만 전달되는 정보는 이미지가 로드되지 않으면 사라진다. 네트워크 오류, CDN 만료, 저장소 이동, 인쇄 시 흑백 변환 등 이미지가 보이지 않는 상황은 언제든지 발생할 수 있다. 핵심 설명은 텍스트로 먼저 제공하고, 이미지는 이해를 돕는 보조 시각 자료로 배치하는 것이 안정적인 문서 설계다. 다이어그램처럼 이미지가 중심인 경우에는 바로 아래 텍스트로 동일한 내용을 설명하는 습관이 중요하다.

HTTP 요청은 클라이언트가 서버로 보내고, 서버가 응답을 반환하는 구조입니다.

![HTTP 요청-응답 사이클 다이어그램](./images/http-cycle.png)

위 다이어그램에서 ①은 클라이언트 요청, ②는 서버 응답을 나타냅니다.

툴팁 텍스트는 보조 정보이며 핵심 맥락을 담기에 적합하지 않다

링크와 이미지 모두 URL 뒤에 "툴팁" 형식으로 제목(title) 속성을 추가할 수 있다. 이 텍스트는 마우스 오버 시 표시되지만 터치 기기에서는 보이지 않으며, 스크린 리더 지원도 일관되지 않다. 중요한 정보는 링크 텍스트나 본문에 넣고, 툴팁은 추가 힌트 수준에서만 사용하는 것이 좋다.

또 하나 자주 생기는 실수는 "이미지 자체가 설명"이라고 가정하는 것이다. 다이어그램만 있고 바로 아래 텍스트 설명이 없으면, 이미지가 깨지거나 스크린 리더가 읽는 순간 정보가 거의 사라진다.

[GitHub 문서](https://docs.github.com "GitHub 공식 문서 사이트")

선택 기준

주의할 점

![diagram](./diagram.png)

이 형태는 파일명이 곧 alt가 되어 버려 독자에게 거의 아무 정보도 주지 못합니다. 설명이 필요한 이미지라면 alt와 본문 설명을 같이 써야 합니다.