<details> 태그로 접기/펼치기
마크다운 자체에는 토글 문법이 없지만, HTML의 <details>와 <summary> 태그로 클릭하면 펼쳐지는 영역을 만들 수 있습니다. GitHub을 비롯한 많은 곳에서 지원합니다.
<details>
<summary>클릭해서 펼치기</summary>
여기에 숨겨둘 내용을 적습니다.
</details>
<summary> 안의 글자가 평소에 보이는 제목이 되고, 그 아래 내용은 접혀 있다가 클릭하면 나타납니다. 자바스크립트 없이 HTML만으로 동작하는 표준 기능이라, 스크립트를 막아둔 환경에서도 잘 작동합니다.
⚠️ 안에 마크다운을 쓰려면 빈 줄이 필요합니다
가장 많이 걸리는 지점입니다. <details> 안에서 마크다운 문법(목록·코드·굵게 등)을 쓰려면 태그와 내용 사이에 빈 줄을 넣어야 합니다.
<details>
<summary>설치 방법</summary>
1. 저장소를 클론합니다
2. `npm install` 실행
3. `npm run dev` 실행
</details>
빈 줄을 넣지 않으면 목록이 목록으로 안 나오고 1. 저장소를 클론합니다 같은 글자가 그대로 보입니다.
이유는 이렇습니다. 마크다운 렌더러는 HTML 블록을 만나면 "여기서부터는 HTML이니 마크다운 해석을 멈춘다"고 판단합니다. 그리고 빈 줄이 나오면 "HTML 블록이 끝났다"고 보고 다시 마크다운 해석을 시작합니다. 그래서 여는 태그 다음에 빈 줄을 넣어야 안쪽 내용이 마크다운으로 처리되고, 닫는 태그 앞에도 빈 줄이 있어야 깔끔하게 마무리됩니다.
마크다운이 아니라 그냥 글자만 넣을 거라면 빈 줄이 없어도 됩니다.
처음부터 펼쳐 두기
<details>에 open 속성을 주면 기본으로 펼쳐진 상태가 됩니다.
<details open>
<summary>기본으로 열려 있음</summary>
내용
</details>
"접을 수는 있지만 일단은 보여주고 싶은" 내용에 씁니다. 독자가 직접 접었다 폈다 할 수 있으면서 첫인상에서는 내용이 드러납니다.
<summary> 안을 꾸미기
제목 부분에 굵게나 코드 서식을 넣고 싶을 때가 있습니다. <summary> 안은 HTML 태그를 쓰는 편이 확실합니다.
<details>
<summary><b>중요</b> — 자세히 보기</summary>
내용
</details>
마크다운 문법(**중요**)은 <summary> 안에서 환경에 따라 처리될 수도, 글자 그대로 나올 수도 있습니다. 확실하게 하려면 HTML 태그를 쓰세요.
중첩할 수도 있습니다
접기 안에 접기를 넣는 것도 됩니다. 다만 각 단계마다 빈 줄 규칙을 지켜야 합니다.
<details>
<summary>플랫폼별 설치</summary>
<details>
<summary>macOS</summary>
brew 명령으로 설치합니다.
</details>
</details>
두 단계까지는 쓸 만하지만 세 단계를 넘어가면 독자가 무엇이 어디에 들어 있는지 파악하지 못합니다. 그 정도로 내용이 많다면 접기가 아니라 문서를 나누는 게 맞습니다.
⚠️ 접어둔 내용은 이런 데서 빠집니다
접기의 진짜 함정은 문법이 아니라 여기에 있습니다.
브라우저 페이지 내 검색(Ctrl+F)
접힌 내용은 화면에 그려지지 않아 브라우저 검색에 잡히지 않는 경우가 많습니다. 최신 크롬처럼 검색어가 접힌 영역에 있으면 자동으로 펼쳐주는 브라우저도 있지만, 모든 환경이 그렇지는 않습니다. 독자가 Ctrl+F로 찾아야 할 만한 핵심 정보는 접어두지 마세요.
인쇄와 PDF 변환
이게 가장 자주 사고로 이어집니다. 접힌 상태 그대로 인쇄하거나 PDF로 내보내면 접힌 내용이 통째로 빠집니다. 문서를 PDF로 제출했는데 절반이 사라진 채로 나가는 일이 여기서 생깁니다.
PDF로 만들 문서라면 접기를 쓰지 않거나, 최소한 open을 붙여 펼친 상태로 두세요. 워드·PDF로 내보낼 때 깨지는 것들에 이 문제를 자세히 적어두었습니다.
플랫폼 이동
<details>는 HTML이라, HTML을 허용하지 않는 곳으로 옮기면 태그가 글자 그대로 노출됩니다. 노션은 자체 토글 블록이 따로 있어서 <details>가 통하지 않고, Slack·Discord도 지원하지 않습니다.
반면 검색엔진이나 GitHub 코드 검색에는 접힌 내용도 잡힙니다. 원문에 그대로 있기 때문입니다. 즉 "안 보이게 하려고" 접는 것은 의미가 없습니다. 그건 주석의 영역이고, 주석도 감추는 것이지 지우는 게 아닙니다.
어디에 쓰면 좋을까
접기가 잘 맞는 곳은 "대부분의 독자에게는 필요 없지만, 필요한 사람에게는 꼭 필요한" 내용입니다.
- 긴 에러 로그나 스택 트레이스
- README의 FAQ, "문제가 생겼을 때" 항목
- 플랫폼별·버전별 분기 설명 (대부분은 자기 것만 보면 됨)
- 참고용 전체 설정 파일
반대로 이런 곳에는 쓰지 마세요.
- 본문의 핵심 내용 — 접으면 안 읽습니다
- 순서대로 따라 해야 하는 단계 — 매번 펼치는 게 번거롭습니다
- 짧은 내용 — 두세 줄을 접으면 펼치는 수고가 더 큽니다
접기는 편해서 남용하기 쉽습니다. 문서 전체가 접힌 제목 목록처럼 보이면 독자는 어디를 눌러야 할지 몰라 그냥 나갑니다. 접기 전에 "이건 정말 대부분의 독자가 안 봐도 되는 내용인가"를 한 번 물어보세요.
정리하면, <details>와 <summary>로 접기를 만들되 안쪽에 빈 줄을 넣는 것을 잊지 마시고, 인쇄·PDF에서 접힌 내용이 빠진다는 점을 기억하세요. 긴 내용을 숨겨 핵심만 보이게 하면 문서 가독성이 크게 올라가지만, 숨길 것과 보여줄 것을 잘못 고르면 반대가 됩니다.