정의 목록
정의 목록은 Markdown의 확장 기능으로, 용어와 해당 정의의 목록을 만드는 데 사용됩니다. 용어집, 용어 설명 또는 매개변수 설명에 일반적으로 사용됩니다.
기본 문법
기본 형식
정의 목록의 기본 형식은 자체 줄에 용어가 있고, 다음 줄에 콜론으로 시작하는 정의가 있습니다:
용어
: 정의 내용렌더링된 출력:
용어 : 정의 내용
여러 용어와 정의
Markdown
: 경량 마크업 언어
: John Gruber이 2004년에 만듦
HTML
: 웹 페이지를 만들기 위한 표준 마크업 언어
: 웹 페이지를 만드는 데 사용됨렌더링된 출력:
Markdown : 경량 마크업 언어 : John Gruber이 2004년에 만듦
HTML : 웹 페이지를 만들기 위한 표준 마크업 언어 : 웹 페이지를 만드는 데 사용됨
고급 사용법
여러 줄 정의
정의 내용은 여러 줄을 포함할 수 있으며, 후속 줄은 들여쓰기가 필요합니다:
용어
: 이것은 정의 내용의 첫 번째 줄입니다
이것은 두 번째 줄로, 최소 한 개의 공백 들여쓰기가 필요합니다
이것은 새로운 단락으로, 최소 한 개의 공백 들여쓰기와 앞의 빈 줄이 필요합니다렌더링된 출력:
용어 : 이것은 정의 내용의 첫 번째 줄입니다 이것은 두 번째 줄로, 최소 한 개의 공백 들여쓰기가 필요합니다
이것은 새로운 단락으로, 최소 한 개의 공백 들여쓰기와 앞의 빈 줄이 필요합니다
정의에서 다른 Markdown 요소 사용
정의에는 링크, 강조, 코드 등 다른 Markdown 요소를 포함할 수 있습니다:
Markdown 문법
: **Markdown**은 여러 텍스트 형식을 지원합니다:
- *이탤릭*과 **굵게**
- [링크](https://www.markdownlang.com)
- `인라인 코드`
- > 블록 인용문
- 목록 및 기타 요소렌더링된 출력:
Markdown 문법 : Markdown은 여러 텍스트 형식을 지원합니다:
- 이탤릭과 굵게
- 링크
인라인 코드블록 인용문
- 목록 및 기타 요소
중첩 정의 목록
일부 Markdown 구현에서는 중첩 정의 목록을 만들 수 있습니다:
외부 용어
: 외부 정의
내부 용어
: 내부 정의
: 다른 내부 정의렌더링된 출력 (지원되는 플랫폼에서):
외부 용어 : 외부 정의
내부 용어 : 내부 정의 : 다른 내부 정의
호환성 및 구현 차이
다양한 플랫폼 지원
| 플랫폼/도구 | 정의 목록 지원 | 특별 문법 | 중첩 지원 |
|---|---|---|---|
| GitHub Markdown | ❌ | - | - |
| GitLab Markdown | ✅ | 표준 | ✅ |
| Jekyll (kramdown) | ✅ | 표준 | ✅ |
| Hugo | ✅ | 표준 | ✅ |
| CommonMark | ❌ | - | - |
| VitePress | ✅ | 표준 | ✅ |
| Pandoc | ✅ | 표준 | ✅ |
HTML 출력 형식
대부분의 Markdown 프로세서는 정의 목록을 HTML <dl>, <dt> 및 <dd> 요소로 변환합니다:
<dl>
<dt>용어</dt>
<dd>정의 내용</dd>
<dt>다른 용어</dt>
<dd>다른 정의</dd>
</dl>다양한 문법 변형
일부 프로세서는 다른 문법 변형을 요구할 수 있습니다:
<!-- 표준 문법 -->
용어
: 정의
<!-- 간결한 문법 (일부 프로세서) -->
용어: 정의
<!-- 추가 공백 문법 (일부 프로세서) -->
용어
: 정의사용 사례
용어집
정의 목록은 용어집이나 어휘를 만드는 데 완벽합니다:
## 프로그래밍 용어집
API
: 애플리케이션 프로그래밍 인터페이스로, 서로 다른 소프트웨어 애플리케이션이 서로 통신할 수 있도록 하는 규칙 집합입니다.
Framework
: 애플리케이션 개발을 위한 표준화된 구조를 제공하는 소프트웨어 라이브러리입니다.
Git
: 프로젝트 개발 과정의 변경사항을 추적하는 데 사용되는 분산 버전 관리 시스템입니다.
IDE
: 통합 개발 환경으로, 코드 에디터와 다양한 개발 도구를 포함하는 소프트웨어 애플리케이션입니다.렌더링된 출력:
프로그래밍 용어집
API : 애플리케이션 프로그래밍 인터페이스로, 서로 다른 소프트웨어 애플리케이션이 서로 통신할 수 있도록 하는 규칙 집합입니다.
Framework : 애플리케이션 개발을 위한 표준화된 구조를 제공하는 소프트웨어 라이브러리입니다.
Git : 프로젝트 개발 과정의 변경사항을 추적하는 데 사용되는 분산 버전 관리 시스템입니다.
IDE : 통합 개발 환경으로, 코드 에디터와 다양한 개발 도구를 포함하는 소프트웨어 애플리케이션입니다.
API 문서
정의 목록은 API 문서에서 매개변수나 옵션을 설명하는 데 사용됩니다:
## 요청 매개변수
user_id
: **필수** - 사용자의 고유 식별자입니다.
: 타입: `integer`
name
: **선택** - 사용자의 표시 이름입니다.
: 타입: `string`
: 기본값: `null`
status
: **선택** - 사용자 상태입니다.
: 타입: `string`
: 허용된 값: `active`, `inactive`, `suspended`
: 기본값: `active`렌더링된 출력:
요청 매개변수
user_id : 필수 - 사용자의 고유 식별자입니다. : 타입: integer
name : 선택 - 사용자의 표시 이름입니다. : 타입: string : 기본값: null
status : 선택 - 사용자 상태입니다. : 타입: string : 허용된 값: active, inactive, suspended : 기본값: active
구성 참고사항
정의 목록은 구성 옵션을 설명하는 데도 적합합니다:
## 구성 옵션
debug
: 디버그 모드를 활성화하거나 비활성화합니다.
: 타입: `boolean`
: 기본값: `false`
: 예시: `debug: true`
log_level
: 로깅의 세부 수준입니다.
: 타입: `string`
: 허용된 값: `error`, `warn`, `info`, `debug`
: 기본값: `info`
: 예시: `log_level: debug`
max_connections
: 허용되는 동시 연결의 최대 수입니다.
: 타입: `integer`
: 기본값: `100`
: 예시: `max_connections: 500`모범 사례
일관성
✅ 권장 사례:
1. **용어와 정의에 일관된 스타일 유지**:
- 용어는 간결한 명사나 구문 사용
- 정의는 문장 형식, 첫 글자 대문자, 마침표로 끝남
- 여러 줄 정의의 경우 일관된 들여쓰기 유지
2. **합리적인 그룹화**:
- 관련된 용어들을 함께 배치
- 제목을 사용하여 다른 정의 목록 분리
3. **기술 용어의 경우**:
- 타입 정보 포함
- 예시 추가
- 필수 또는 선택 표시
❌ 피해야 할 사례:
1. 용어가 너무 길어 한 줄을 초과
2. 용어에서 큰 형식의 텍스트 사용
3. 명확한 분류 부족
4. 관련 없는 정보를 포함한 정의대안 해결책
정의 목록을 지원하지 않는 플랫폼에서는 다른 형식을 사용하여 시뮬레이션할 수 있습니다:
<!-- 굵게와 들여쓰기 사용 -->
**용어**
정의 내용
**다른 용어**
다른 정의 내용
<!-- 표 사용 -->
| 용어 | 정의 |
|------|------|
| API | 애플리케이션 프로그래밍 인터페이스 |
| IDE | 통합 개발 환경 |
<!-- 제목과 단락 사용 -->
### 용어
정의 내용
### 다른 용어
다른 정의 내용실제 적용 예시
소프트웨어 문서
## 시스템 요구사항
운영체제
: **Windows**: Windows 10 이상
: **macOS**: macOS 10.14 (Mojave) 이상
: **Linux**: Ubuntu 18.04+, Debian 10+, CentOS 7+
하드웨어
: **프로세서**: 쿼드코어 2.0 GHz 이상
: **메모리**: 최소 8GB RAM, 권장 16GB
: **저장소**: 최소 10GB 사용 가능한 공간, SSD 저장소
네트워크
: 광대역 인터넷 연결 (최소 10 Mbps)
: 포트 80, 443, 22에서 아웃바운드 연결 허용학술 문서
## 연구 용어
Dataset
: 분석이나 평가에 사용되는 데이터 모음입니다.
: 이 연구에서는 공개 저장소의 샘플을 사용했습니다 (n=1000).
Variable
: **독립 변수**: 연구자가 조작하는 입력 요인입니다.
이 연구에서 독립 변수는 환경 온도였습니다.
: **종속 변수**: 연구에서 측정되는 출력 요인입니다.
이 연구에서 종속 변수는 처리 속도였습니다.
: **통제 변수**: 실험에서 일정하게 유지되는 요인입니다.
이 연구에서는 습도와 프로세서 부하가 포함되었습니다.
Significance Level
: 통계 분석에서 결과가 의미 있는지 판단하는 데 사용되는 확률 임계값입니다.
: 이 연구에서는 p < 0.05를 유의성 기준으로 사용했습니다.일반적인 문제 및 해결책
정의 목록이 표시되지 않음
정의 목록이 올바르게 표시되지 않는 경우:
- 플랫폼이 정의 목록 문법을 지원하는지 확인
- 용어와 정의 사이에 빈 줄이 없는지 확인
- 콜론 앞에 적절한 공백이 있는지 확인 (일부 프로세서는 특정 요구사항이 있을 수 있음)
- 들여쓰기를 늘리거나 문법 변형을 변경해보기
중첩 목록 문제
중첩 정의 목록은 일부 프로세서에서 문제가 있을 수 있습니다:
- 들여쓰기 수준 증가 (예: 내부 용어는 4개 또는 8개 공백 사용)
- 계층 간 적절한 빈 줄 확보
- 문제가 지속되면 다른 구조 사용 고려 (예: 일반 목록)
형식 문제
정의에서 형식이 올바르지 않은 경우:
- 모든 단락과 요소의 들여쓰기가 올바른지 확인
- 블록 수준 요소(예: 코드 블록, 목록)가 정의 내에서 올바른 빈 줄 분리를 가지고 있는지 확인
- 들여쓰기 양을 늘려보기
관련 문법
도구 및 플러그인
- markdown-it-deflist: markdown-it에 정의 목록 지원 추가
- kramdown: 기본 정의 목록 Markdown 파서
- remark-definition-list: remark 파서용 정의 목록 플러그인
정의 목록은 Markdown의 강력한 확장 기능으로, 특히 용어, 매개변수 및 구성의 설명 문서를 만드는 데 적합합니다. 모든 Markdown 프로세서가 이 문법을 지원하지는 않지만, 지원되는 플랫폼에서는 기술 문서에 대한 명확하고 구조화된 형식을 제공하여 복잡한 정보를 더 쉽게 이해하고 참조할 수 있게 합니다.