기본 요소 가이드

마크다운 이미지 경로 규칙

![]()도 아래처럼 사용 가능합니다. 경로 앞의 ./를 생략해도 자동으로 보정됩니다.

![](img.png)        # 현재 문서 기준으로 자동 ./ 보정
![](./img.png)      # 현재 문서 기준
![](dir/a.png)      # 현재 문서 기준으로 자동 ./ 보정
![](/img.png)       # 사이트 루트(public) 기준

단, 표준 마크다운 ![]() 문법은 alt/title 자동 추출과 모달 기능이 적용되지 않습니다. 캡션과 클릭 확대가 필요한 경우 ![[...]] 문법을 우선 사용하세요.

실제 예시 이미지

![예제 이미지](./profile_img.png '예제 이미지')

렌더링 결과

이미지 클릭 모달

![[...]] 문법은 이미지 위치에 따라 동작이 달라집니다.

• 단독 줄(블록): 본문에 이미지가 바로 렌더링됩니다. 클릭하면 원본 크기 모달이 열립니다.
• 텍스트 사이(인라인): 본문에는 클릭 트리거 텍스트가 나오고, 클릭하면 이미지 모달이 열립니다.

![[profile_img.png|예제 이미지]]

렌더링 결과

여기서 ![[profile_img.png|예제 이미지 확대 보기]] 를 클릭하면 모달로 세부 항목을 확인할 수 있습니다.

작성법

![[test video.mp4]]

mp4 파일을 지정하면 동일 경로의 webm 파일을 자동으로 탐색해 1순위 소스로 추가합니다. 브라우저가 WebM을 우선 재생하고, 지원하지 않을 때 MP4로 폴백합니다.

렌더링 결과(생성 소스 예시)

<!-- 자동 생성 결과 -->
<source src="./test%20video.webm" type="video/webm" />
<source src="./test%20video.mp4" type="video/mp4" />

webm, mov, ogg 등 다른 확장자는 해당 파일 단독으로 소스가 설정됩니다.

WebP 애니메이션 파일

애니메이션 GIF와 Animated WebP는 자동으로 감지되어 일반 이미지와 다르게 처리됩니다. 모달 기능이 적용되지 않고 <img> 태그로 직접 렌더링되어 애니메이션이 그대로 재생됩니다.

![[webp animation sample.webp]]

렌더링 결과

텍스트 토큰

공백으로 감싼 위치에서 자동 변환됩니다. 텍스트를 입력하면 렌더링 시 아이콘 스팬으로 교체됩니다.

초기 점검은 다음 순서로 진행합니다: 준비 :❯ 검토 :❯ 적용 :❯ 검증.

- 준비 단계: 입력값 확인
- 적용 단계: 변경 반영
- 검증 단계: 결과 비교

참고 명령: `pnpm build`

디렉티브

명시적으로 삽입할 때는 디렉티브를 사용합니다. ::next 계열은 공백 기준 인라인 토큰으로 렌더링되며, ::n ::r ::l ::u ::d는 각각 next/right/left/up/down의 단축 별칭입니다.

::next ::right ::left ::up ::down
::n ::r ::l ::u ::d ← 단축 별칭

툴팁 디렉티브

풋노트 이동 방식은 그대로 유지하면서, 본문 특정 문구에 hover 툴팁을 붙일 때 사용합니다. 각주를 쓸 만큼 길지 않은 보조 설명이나 약어 풀이에 적합합니다.

:tt[마우스 오른쪽 버튼으로 클릭하면 이어지는 메뉴]

긴 문장/링크 포함 예시

툴팁 내부에는 마크다운 링크도 넣을 수 있습니다. 단, 링크 클릭은 툴팁이 열린 상태에서만 동작합니다.

작성법(긴 문장):

여기서는 :tt[이 항목은 관리자 권한이 필요한 설정이며, 저장 전에 현재 값과 변경 예정 값을 함께 확인한 뒤 적용 여부를 결정해야 합니다.] 툴팁 설명을 확인합니다.

렌더링 결과(긴 문장):

여기서는 주 툴팁 설명을 확인합니다.

작성법(링크 포함):

자세한 정책은 [운영 가이드](https://example.com/guide)를 참고하고 :tt[원문은 [정책 문서](https://example.com/policy/tooltips)에서 확인하세요.] 툴팁 설명도 확인하세요.

렌더링 결과(링크 포함):

자세한 정책은 운영 가이드를 참고하고 주 툴팁 설명도 확인하세요.

색상 디렉티브

:blue, :gray, :red는 테마에 맞게 미리 정의된 색상입니다. 가장 많이 쓰는 세 가지 강조 색상을 간결하게 사용할 수 있습니다.

:blue[파랑 텍스트]
:gray[그레이 텍스트]
:red[레드 텍스트]

작성법

:blue[파랑 텍스트]
:gray[그레이 텍스트]
:red[레드 텍스트]

:color[커스텀 파랑]{value=#2563eb}
:c[커스텀 그레이]{v=#6b7280}
:색[커스텀 레드]{color=#dc2626}

렌더링 결과(인라인)

파랑 · 그레이 · 레드

렌더링 결과(멀티 라인)

문서 본문에서는 핵심 단계를 먼저 안내하고, 보조 조건은 별도 줄로 분리해 가독성을 높입니다. 오류 대응 문구는 즉시 확인 필요처럼 행동 중심 문장으로 작성하면 전달력이 좋아집니다.

• 핵심 단계: 작업 순서 안내
• 보조 조건: 적용 범위 및 제약
• 즉시 확인 필요: 대응 우선순위

임의 색상 지정

:color[텍스트]{value=색상} 형태로 임의 HEX 값이나 CSS 색상 이름을 직접 지정할 수 있습니다. value, v, color 모두 동일한 속성 이름입니다.

:color[강조 텍스트]{value=#2563eb}
:c[보조 텍스트]{v=gray}
:색[경고 텍스트]{color=red}

HTML 방식

<span style="color:...">텍스트</span> 형태도 그대로 사용할 수 있습니다.

<span style="color:#2563eb">파랑 텍스트</span>
<span style="color:#6b7280">그레이 텍스트</span>
<span style="color:#dc2626">레드 텍스트</span>

파랑 텍스트, 그레이 텍스트, 레드 텍스트

블록 여백 디렉티브

단락 사이 수직 간격이 필요할 때 사용합니다. 숫자가 클수록 여백이 넓어지며 단위는 rem입니다.

::여백 ← 기본 (0.95em)
::여백1 ← 1rem
::여백2 ← 2rem
::여백3 ← 3rem
::여백4 ← 4rem
::여백5 ← 5rem

이미지나 비디오 앞뒤, 또는 별도의 공간 구분이 필요한 섹션 경계에 사용합니다. 마크다운 빈 줄만으로 부족한 경우에 적합합니다.

인라인 여백

단락을 나누지 않고 한 문장 안에서 수평 간격을 만들 때 사용합니다.

앞 문장 [여백] 뒤 문장

줄바꿈 (<br>)

단락을 나누지 않고 줄만 바꿀 때 사용합니다. 두 가지 방법이 지원됩니다.

첫 줄\
둘째 줄

첫 줄
둘째 줄

• \ (백슬래시) — 의도가 명확하고 에디터의 trailing whitespace 자동 제거 영향 없음 (권장)
• 줄 끝 스페이스 2칸 — CommonMark 표준이지만 에디터 설정에 따라 자동 제거될 수 있음

렌더링 결과

앞 문장

뒤 문장

줄바꿈 예시 — 백슬래시:
두 번째 줄

줄바꿈 예시 — 스페이스 2칸:
두 번째 줄

작성법

설정 변경 이력을 문서 본문에서 간단히 언급하고, 상세 근거는 각주로 분리할 수 있습니다.[^policy]

각주를 여러 개 사용할 때는 번호만 늘리는 방식보다 용도별 이름을 함께 사용하는 것이 유지보수에 유리합니다.[^naming]

[^policy]: 변경 사유, 적용 범위, 검증 방법을 각주에 분리하면 본문 가독성을 유지하면서 추적 정보를 남길 수 있습니다.
[^naming]: 예: `policy`, `rollback`, `reference`처럼 의미가 드러나는 키를 사용하면 문서 수정 시 혼동이 줄어듭니다.

• [^policy]가 본문에서 먼저 등장 → 1번, [^naming]이 다음 등장 → 2번 으로 자동 부여
• 키 이름(policy, naming)은 유지보수용 식별자로만 사용되며 출력에는 숫자만 표시됨
• 정의 순서는 번호에 영향 없음 — 본문 참조 순서가 기준
• 정의는 문서 어디에 두어도 무방하지만 관리 편의상 문서 하단에 모아 두는 것이 일반적

렌더링 결과

설정 변경 이력을 문서 본문에서 간단히 언급하고, 상세 근거는 각주로 분리할 수 있습니다.¹

각주를 여러 개 사용할 때는 번호만 늘리는 방식보다 용도별 이름을 함께 사용하는 것이 유지보수에 유리합니다.²