GitHub 및 문서용 Markdown 접기/펼치기 섹션 생성 완벽 가이드
Markdown 접기/펼치기 섹션이란 무엇인가요?
Markdown은 일반 텍스트 문서, README 파일 및 개발자 문서를 서식화하는 간편함으로 널리 사용됩니다. 그러나 표준 Markdown 구문은 대화형 아코디언 위젯이나 접기/펼치기 토글을 기본적으로 지원하지 않습니다. 무거운 JavaScript에 의존하지 않고 이를 해결하기 위해 최신 Markdown 파서는 HTML5 인라인 태그인 <details> 및 <summary>를 지원합니다.
무료 온라인 Markdown 접기/펼치기 섹션 생성기를 사용하면 긴 기술 사양, 로그 출력, FAQ, 코드 예제 등을 깔끔하게 접을 수 있는 드롭다운 컨테이너로 즉시 변환할 수 있습니다.
HTML5 Details 및 Summary 구문 분석
모든 Markdown 아코디언 토글의 기본은 두 가지 표준 HTML 태그를 바탕으로 합니다:
<details>래퍼 태그: 표시되는 제목과 숨겨진 콘텐츠를 모두 담는 컨테이너입니다. 선택적open속성 (<details open>)을 추가하면 페이지 로드 시 기본적으로 펼쳐진 상태가 됩니다.<summary>제목 태그: 사용자가 클릭하여 내부 콘텐츠를 토글할 수 있는 제목을 정의합니다.
표준 구문 구조 예시:
<details>
<summary>상세 설치 지침을 보려면 여기를 클릭하세요</summary>
### 사전 요구 사항
- Node.js v18+
- npm 또는 yarn
다음 명령어를 실행하여 종속성을 설치하세요:
```bash
npm install utiliome-tools
</details>
```[!IMPORTANT] Markdown 파서를 위한 팁: GitHub Flavored Markdown과 같은 대부분의 마크다운 프로세서는 닫는
</summary>태그 직후에 빈 줄 하나가 필요합니다. 이 빈 줄이 없으면 중첩된 Markdown 구문(제목###, 목록-, 코드 블록 ``` 등)이 파싱되지 않고 일반 텍스트로 표시됩니다.
펼치기/접기 콘텐츠의 주요 활용 사례
1. GitHub README 파일 정리
리포지토리 README에 환경 변수, 변경 로그, API 참조를 모두 나열하면 페이지가 너무 길어집니다. 긴 로그나 환경 설정을 <details> 블록으로 감싸면 README를 깔끔하게 유지할 수 있습니다.
2. 깔끔한 FAQ 페이지 구축
자주 묻는 질문은 아코디언 레이아웃에 완벽히 어울립니다. 사용자는 질문을 빠르게 훑어보고 필요한 답변만 펼쳐볼 수 있습니다.
3. 테스트 결과 및 스택 트레이스 숨기기
GitHub이나 GitLab에서 PR을 작성할 때 거대한 테스트 출력이나 스택 트레이스를 접기 섹션으로 감싸면 토론 흐름을 방해하지 않고 전체 진단 정보를 공유할 수 있습니다.
4. 대화형 문서 및 지식 기반 구성
Docusaurus, MkDocs, Hugo, Jekyll 등에서 HTML details 요소를 쉽게 활용하여 가이드를 체계적으로 구성할 수 있습니다.
플랫폼 호환성 가이드
| 플랫폼 / 파서 | 접기 <details> 지원 |
Details 내 Markdown 지원 | 참고 사항 |
|---|---|---|---|
| GitHub (GFM) | 완벽 지원 | 완벽 지원 (<summary> 뒤 빈 줄 필요) |
README.md, PR 및 이슈 댓글에 최적. |
| GitLab | 완벽 지원 | 완벽 지원 | 표준 HTML details/summary 파싱. |
| Notion | 네이티브 토글 리스트 | 임포트를 통해 지원 | 토글 블록으로 깔끔하게 임포트됨. |
| Obsidian | 네이티브 및 HTML 지원 | 완벽 지원 | 플러그인 토글 및 표준 HTML 태그 모두 지원. |
| Azure DevOps | 부분 지원 | 기본 지원 | 위키 페이지에서 간단한 details 태그 지원. |
| Jekyll / Hugo | 완벽 지원 | Markdown 확장 설정 필요 | 정적 사이트 빌드 시 유효한 HTML 출력. |
Markdown 아코디언 디자인 모범 사례
- 명확한 제목 사용: "더 보기" 대신 "전체 벤치마크 결과 보기"처럼 명확한 제목을 사용하세요.
- 이모지 활용: 제목 태그 안에 화살표나 이모지(
▶️,🔍)를 추가하여 클릭 가능한 요소임을 직관적으로 알려주세요. - 적절한 들여쓰기 유지: 구문 오류를 방지하기 위해 중첩된 블록의 들여쓰기를 올바르게 유지하세요.