Cloudwiki/위키 문법 가이드/컴포넌트

# 컴포넌트 문법

더욱 풍부한 페이지 꾸미기에 사용할 수 있는 문법입니다.

## 컴포넌트

모든 컴포넌트 요소는  형식으로 작성합니다.
색상은 입력하지 않아도 무방한 선택사항입니다.

컴포넌트의 색상 문법은 팔레트`{palette:팔레트}` 또는 커스텀 색상`{bg:컬러코드}{color:컬러코드}` 모두 지원합니다. 컴포넌트 문법 앞에 컬러 문법을 공백 없이 붙이면 적용됩니다. 팔레트 뒤에 커스텀 색상을 붙이는 경우, 해당 색상이 덮어씌워집니다.
`{bi:`, `{mdi: ` 아이콘을 앞에 붙이면 아이콘을 컴포넌트 내부에 포함시킵니다.


### 배지
기본 사이즈의 칩입니다.

[배지]
[배지]
[배지]
```
{badge:배지}
{palette:primary}{badge:배지}
{bi:bootstrap-fill}{palette:primary}{badge:배지}
```

### 태그
배지보다 작은 칩입니다.

[태그]
[태그]
[태그]
```
{tag:태그}
{palette:primary}{tag:태그}
{bi:bootstrap-fill}{palette:primary}{tag:태그}
```

### 스탯
제목과 내용으로 나눠진 칩입니다.

$1 (가격)
$1 (가격)
$1 (가격)
```
{palette:primary}{stat:$1|가격}
{palette:primary}{stat:$1|가격}
{bi:bootstrap-fill}{palette:primary}{stat:$1|가격}
```
### 버튼
링크 버튼입니다.

[버튼](https://youtu.be/dQw4w9WgXcQ?si=2jdHDmAX8gMPt3kI)
[버튼](https://youtu.be/dQw4w9WgXcQ?si=2jdHDmAX8gMPt3kI)
```
{palette:primary}{button:버튼|https://youtu.be/dQw4w9WgXcQ?si=2jdHDmAX8gMPt3kI}
{palette:primary}{bi:bootstrap-fill}{button:버튼|https://youtu.be/dQw4w9WgXcQ?si=2jdHDmAX8gMPt3kI}
```

### 키보드 키
단축키를 키캡 모양으로 표시합니다. `+` 기호로 여러 키를 묶으면 조합 키로 렌더됩니다.
키보드 키 문법은 아이콘 삽입이 불가능합니다.

Ctrl+C 로 복사, Ctrl+Shift+K 로 취소선.
Enter
```
{kbd:Ctrl+C} 로 복사, {kbd:Ctrl+Shift+K} 로 취소선.
{palette:primary}{kbd:Enter}
```

### 진행도 바
퍼센트(0~100) 또는 `a/b` 분수 형태로 진행도를 표시합니다. 뒤에 `|라벨`을 붙이면 라벨이 함께 표시됩니다.
배경 컬러 문법은 진행바, 글씨색 문법은 진행도 텍스트의 색을 변경합니다.

70%
로딩 중: 70%
완료된 작업: 7/10 (70%)
완료율: 85%
연료: 3/10 (30%)
```
{progress:70}
{progress:70|로딩 중}
{progress:7/10|퀘스트 진행도}
{palette:success}{progress:85|완료율}
{palette:danger}{mdi:fire}{progress:3/10|체력}
```

### 가로선
`{hr}` 토큰은 블록 가로선(`<hr class="wiki-block-hr">`)을 삽입합니다.
표준 마크다운 `---` 과 달리 `{hr}` 은 인라인 토큰으로 처리되어 다른 컴포넌트와 같은 문단/단락 안에 자연스럽게 섞어 쓸 수 있고, `:::card` · `:::callout` · `:::tab` · `:::item` 등 블록 디렉티브 본문 내부에서도 안전하게 동작합니다.
색상·아이콘 프리픽스는 지원하지 않습니다.

상단 내용

하단 내용

```
상단 내용
{hr}
하단 내용
```

### 줄바꿈
`{br}` 토큰은 인라인 줄바꿈(`<br>`)을 삽입합니다.
표 셀, 틀 인자, `:::card`, `:::info` 같은 콜아웃, 펼치기/접기 제목, `{badge:...}` 같은 인라인 컴포넌트 내부처럼 평소 줄바꿈을 직접 입력할 수 없는 위치에서도 자유롭게 사용할 수 있습니다.
코드 블록과 인라인 코드 안에서는 토큰이 그대로 출력되어, 문서화 예제 안에 안전하게 노출할 수 있습니다.

>  위키 에디터의 표 셀 안에서 Shift+Enter 단축키를 누르면 `{br}` 토큰이 자동으로 삽입됩니다. 자세한 내용은 [[Cloudwiki/에디터/표]] 의 *셀 안 줄바꿈* 절을 참고하세요.

상단 내용
하단 내용

| 셀 1 | 줄바꿈
이 들어간 셀 |
| --- | --- |
| 내용 A | 내용 B |

```
상단 내용{br}하단 내용

| 셀 1 | 줄바꿈{br}이 들어간 셀 |
| --- | --- |
| 내용 A | 내용 B |
```

## 블록
블록 문법 내부에 다른 블록 문법을 삽입하는것이 가능합니다.

`grid`, `row` 문법을 중첩해 사용하는것은 권장하지 않습니다.

### 카드

제목과 내용 부분에 각각 다른 색상을 적용할 수 있습니다.
컬러 팔레트와 커스텀 색상을 모두 지원합니다.

카드 제목
내용


```
:::card {palette:typescript} 카드 제목
{palette:success}내용
:::
```

### 콜아웃
내용을 주제별 색상·아이콘과 함께 강조해 보여주는 박스입니다. 6가지 타입을 지원합니다.

| 타입 | 용도 | 기본 제목 |
| :---: | --- | --- |
| info | 정보 안내 | 정보 |
| tip | 유용한 팁 | 팁 |
| success | 성공/완료 메시지 | 성공 |
| warning | 주의 사항 | 주의 |
| danger | 위험·경고 | 위험 |
| note | 일반 메모 | 노트 |

타입 뒤에 공백으로 제목을 적으면 기본 제목을 덮어씁니다. 제목을 생략하면 기본 제목이 표시됩니다. 헤더 색은 타입 뒤에 `{bg:}`/`{color:}`/`{palette:}` 토큰으로, 본문 색은 카드와 동일하게 본문 맨 앞에 같은 토큰을 붙여 지정합니다.

정보:
가벼운 안내 문구를 담습니다.


팁: 단축키
`{kbd:Ctrl+S}` 로 저장할 수 있습니다.


주의: 백업 필수
배포 전 반드시 데이터베이스 백업을 확인하세요.


위험: 파괴적 작업
`DROP TABLE` 은 되돌릴 수 없습니다.


```
:::info
가벼운 안내 문구를 담습니다.
:::

:::tip 단축키
`{kbd:Ctrl+S}` 로 저장할 수 있습니다.
:::

:::warning 백업 필수
배포 전 반드시 데이터베이스 백업을 확인하세요.
:::

:::danger 파괴적 작업
`DROP TABLE` 은 되돌릴 수 없습니다.
:::
```

### 임베드
임베드 카드입니다. 
왼쪽에 강조선을 두고 본문을 감싸는 형태로 표시되며, 본문 안에 유튜브 등 임베딩이 지원되는 링크를 한 줄로 넣으면 자동 임베드가 함께 표시됩니다.

```
:::embed <제목> {color:강조색} (제목·색 모두 선택사항)
내용
:::
```
- 제목은 `:::embed` 뒤에 공백으로 이어 붙입니다. 생략 가능.
- `{color:...}` 또는 `{bg:...}` 토큰 한 개를 헤더에 붙이면 왼쪽 강조선 색으로 적용됩니다.
- 본문 컬러는 지원하지 않습니다.
- 색을 생략하면 기본 강조선(링크 색)이 사용됩니다.

Bad Apple!!
https://youtu.be/FtutLA63Cp8?si=DMEsZCTd7NJWW_LP

본문에 자유롭게 설명을 쓸 수 있습니다. YouTube · Spotify · Google Maps · 니코니코 등 임베딩을 지원하는 링크 삽입을 권장합니다.



제목과 색을 생략하면 기본 색 강조선의 단순한 박스로 렌더됩니다.


```
:::embed Bad Apple!! {palette:reverse}
https://youtu.be/FtutLA63Cp8?si=DMEsZCTd7NJWW_LP

본문에 자유롭게 설명을 쓸 수 있습니다. YouTube · Spotify · Google Maps · 니코니코 등 임베딩을 지원하는 링크 삽입을 권장합니다.
:::

:::embed
제목과 색을 생략하면 기본 색 강조선의 단순한 박스로 렌더됩니다.
:::
```


### 그리드

컴포넌트 요소들을 동적으로 화면 레이아웃에 따라 반응형으로 배치합니다.


제목 (내용)
제목 (내용)
제목 (내용)
제목 (내용)
제목 (내용)
제목 (내용)

| 제목1 | 제목2 | 제목3 |
| --- | --- | --- |
| 내용1 | 내용2 | 내용3 |

| 제목1 | 제목2 | 제목3 |
| --- | --- | --- |
| 내용1 | 내용2 | 내용3 |


```
:::grid
{palette:primary}{stat:제목|내용}
{palette:secondary}{stat:제목|내용}
{palette:success}{stat:제목|내용}
{palette:info}{stat:제목|내용}
{palette:warning}{stat:제목|내용}
{palette:danger}{stat:제목|내용}

| 제목1 | 제목2 | 제목3 |
| --- | --- | --- |
| 내용1 | 내용2 | 내용3 |

| 제목1 | 제목2 | 제목3 |
| --- | --- | --- |
| 내용1 | 내용2 | 내용3 |
:::
```


### row

컴포넌트 요소들을 가로로 배치합니다.
내용이 길어지면 가로로 스크롤해 볼 수 있습니다.


제목 (내용)
제목 (내용)
제목 (내용)
제목 (내용)
제목 (내용)
제목 (내용)

| 제목1 | 제목2 | 제목3 |
| --- | --- | --- |
| 내용1 | 내용2 | 내용3 |

| 제목1 | 제목2 | 제목3 |
| --- | --- | --- |
| 내용1 | 내용2 | 내용3 |


```
:::row
{palette:primary}{stat:제목|내용}
{palette:secondary}{stat:제목|내용}
{palette:success}{stat:제목|내용}
{palette:info}{stat:제목|내용}
{palette:warning}{stat:제목|내용}
{palette:danger}{stat:제목|내용}

| 제목1 | 제목2 | 제목3 |
| --- | --- | --- |
| 내용1 | 내용2 | 내용3 |

| 제목1 | 제목2 | 제목3 |
| --- | --- | --- |
| 내용1 | 내용2 | 내용3 |
:::
```


### 탭

여러 패널을 하나의 영역에서 전환해 보여주는 컴포넌트입니다.
부모 `:::tabs` 안에 자식 `:::tab 제목` 을 나열합니다. 첫 번째 탭이 기본 활성 탭이며, 탭 스트립은 항상 좌측 정렬됩니다.
자식 제목 뒤에 `{icon:bi-...}` 또는 `{icon:mdi-...}` 토큰으로 아이콘을 붙일 수 있습니다.


개요
이 문서의 개요를 적습니다.

사용법
사용 방법을 단계별로 안내합니다.

자주 묻는 질문
- Q1: ...
- Q2: ...



```
:::tabs
:::tab 개요 {icon:bi-info-circle}
이 문서의 개요를 적습니다.
:::
:::tab 사용법 {icon:bi-book}
사용 방법을 단계별로 안내합니다.
:::
:::tab 자주 묻는 질문
- Q1: ...
- Q2: ...
:::
:::
```


### 아코디언

세로로 배치된 항목들을 펼쳤다 접을 수 있는 컴포넌트입니다.
부모 `:::accordion` 안에 자식 `:::item 제목` 을 나열합니다. 기본은 단일 열림 모드로, 한 항목을 펼치면 나머지는 자동으로 접힙니다.

자식 제목 뒤에 `{open}` 토큰을 붙이면 해당 항목이 초기에 펼쳐진 상태로 시작합니다. 단일 열림 모드에서 `{open}` 이 여러 개 있으면 첫 번째만 인정됩니다.
부모 헤더에 `{multiple}` 토큰을 붙이면 다중 열림 모드로 전환되어 여러 항목을 동시에 열어둘 수 있습니다.
탭과 동일하게 자식 제목에 `{icon:bi-...}` / `{icon:mdi-...}` 아이콘을 붙일 수 있습니다.

아코디언 항목 헤더는 본문 헤딩이 아니므로 목차(TOC)·자동 번호·섹션 편집 버튼 대상에서 제외됩니다. 항목 본문 안에 직접 작성한 `## 제목` 등 일반 헤딩은 평소대로 TOC 에 표시됩니다.


자주 묻는 질문 1
초기 진입 시 펼쳐진 상태로 표시됩니다.

자주 묻는 질문 2
다른 항목을 펼치면 자동으로 접힙니다.

자주 묻는 질문 3
일반 항목입니다.



```
:::accordion
:::item 자주 묻는 질문 1 {open}
초기 진입 시 펼쳐진 상태로 표시됩니다.
:::
:::item 자주 묻는 질문 2 {icon:bi-question-circle}
다른 항목을 펼치면 자동으로 접힙니다.
:::
:::item 자주 묻는 질문 3
일반 항목입니다.
:::
:::
```


항목 A
다중 열림 모드입니다.

항목 B
여러 항목을 동시에 펼쳐둘 수 있습니다.



```
:::accordion {multiple}
:::item 항목 A {open}
다중 열림 모드입니다.
:::
:::item 항목 B {open}
여러 항목을 동시에 펼쳐둘 수 있습니다.
:::
:::
```

### 스탭

번호가 매겨진 단계를 순서대로 보여주는 컴포넌트입니다.
부모 `:::steps` 안에 자식 `:::step 제목` 을 나열합니다. 각 단계에는 자동으로 1번부터 순번이 매겨집니다.

자식 제목 뒤에 `{status:done}` · `{status:current}` · `{status:todo}` 토큰으로 단계의 상태를 표시할 수 있습니다.

| 상태 | 마커 아이콘 | 의미 |
| :---: | :---: | --- |
| `done` | 채워진 체크 | 완료된 단계 |
| `current` | 채워진 원 | 현재 진행 중인 단계 (`aria-current="step"` 부여) |
| `todo` | 빈 원 | 아직 진행하지 않은 단계 (기본값) |

스탭 항목 헤더는 본문 헤딩이 아니므로 목차(TOC)·자동 번호·섹션 편집 버튼 대상에서 제외됩니다. 항목 본문 안에 작성한 일반 헤딩은 평소대로 TOC 에 표시됩니다.


1. 저장소 클론
`git clone` 으로 저장소를 받아옵니다.

2. 의존성 설치
`npm install` 을 실행합니다.

3. 개발 서버 실행
`npm run dev` 로 로컬에서 확인합니다.



```
:::steps
:::step 저장소 클론 {status:done}
`git clone` 으로 저장소를 받아옵니다.
:::
:::step 의존성 설치 {status:current}
`npm install` 을 실행합니다.
:::
:::step 개발 서버 실행
`npm run dev` 로 로컬에서 확인합니다.
:::
:::
```