Cloudwiki/위키 문법 가이드/요약본(AI용)
제목: Cloudwiki/위키 문법 가이드/요약본-AI용
# Cloudwiki 문법 — AI 에이전트 축약 레퍼런스
> 이 문서는 AI 에이전트가 Cloudwiki 문서를 작성·편집할 때 빠르게 참조하기 위한 압축본입니다.
> 전체 가이드: [[Cloudwiki/위키 문법 가이드]], [[Cloudwiki/위키 문법 가이드/컴포넌트]]
---
## 주의사항
- 헤딩(`##`, `###` 등)에 번호를 직접 적지 말 것. 위키가 자동 부여함. (`## 1. 개요` ❌ → `## 개요` ✅)
- 코드 블록 내부는 위키 문법이 동작하지 않음.
---
## 1. 기본 마크다운 (Cloudwiki 전용 확장만 주의)
표준 마크다운과 동일하나, 아래는 Cloudwiki 전용 확장이므로 별도 숙지.
```
==텍스트== ← 단독은 효과 없음(형광펜 기본 강조 제거). {bg:}/{color:}/{fs:}/{palette:} 접두 토큰 전용 형식 캐리어. 예: {bg:yellow}==형광펜==
__밑줄__
{size:icon|small|medium|full}{align:left|center|right}{caption:캡션 텍스트}
icon은 텍스트 인라인 삽입 가능. {size:} 옵션은 생략 가능 (생략시 full과 동일)
{align:}/{caption:} 은 {size:} 와 같은 자리의 접미 토큰(순서 무관, 괄호 뒤 공백 없이).
이미지가 문단에 단독일 때만 figure/figcaption 으로 렌더 — 텍스트와 섞이면 무시됨.
표 셀 병합 (Cloudwiki 전용):
{>} 오른쪽 병합 {<} 왼쪽 병합 {^} 위 병합 {><} 가운데로 병합
※ 색상 문법은 병합 셀이 아닌 일반 내용 칸에 작성
줄바꿈 토큰 {br} (Cloudwiki 전용):
표 셀, 틀 인자, :::card/:::info 등 콜아웃, 펼치기/접기 제목, {badge:...} 같은 인라인 컴포넌트 내부처럼
평소 직접 줄바꿈을 입력할 수 없는 위치에서 인라인으로 삽입하면 그 자리에서 줄바꿈이 적용됨.
표준 마크다운은 표 셀이 단일 라인이어야 하므로 특히 표 셀에서 유용.
코드 블록/인라인 코드 안에서는 토큰이 그대로 텍스트로 출력됨(문서화 예제에 안전하게 노출 가능).
에디터에서 표 셀 안에 커서를 두고 Shift+Enter 로 {br} 빠르게 삽입 가능.
표 옵션 토큰 (Cloudwiki 전용, 표 헤더 행 바로 윗줄에 단독 라인으로 작성):
{table:left|center|right} 표 전체 정렬 {w:50~100%} 표 너비 (10% 단위)
{caption:제목} 표 상단 캡션 {sticky-header} 스크롤 시 헤더 고정
{sortable} 헤더 클릭 정렬 (열람 전용, 데이터 불변) {row-header} 첫 열 세로 헤더화
열 너비: 구분 행 셀에 {w:NN%} — 예: | :--- {w:30%} | --- |
예:
{table:center}{w:70%}{caption:분기별 실적}
| 분기 | 매출 |
| --- {w:30%} | --- |
| 1Q | 120 |
※ 최상위 표 전용 (인용구/리스트 안 불가). 알 수 없는 토큰이 섞인 라인은 일반 텍스트로 표시됨.
※ {sortable} 은 병합 셀({<}{>}{^}{><})이 있는 표에서 자동 비활성.
체크리스트 상태 (Cloudwiki 확장):
- [ ] 미완료 - [x] 완료 - [~] 또는 - [/] 진행 중
※ 표준 GFM 의 [ ]/[x] 에 더해 진행 중([~] / [/]) 상태 지원. 순서 목록(1. [~])도 가능.
```
---
## 2. 위키 확장 문법
### 위키 내부 링크
```
[[문서제목]]
[[문서제목|표시텍스트]]
[[문서제목#1.1]] ← 특정 목차로 이동
[[문서제목#1.1|표시텍스트]]
```
### 틀 (Transclusion)
```
{{틀:틀이름}}
{{틀:틀이름|파라미터=값|파라미터2=값2}}
```
틀 본문에서: `{{{파라미터이름}}}` 으로 파라미터 수신.
틀 조건문 (파서 함수, MediaWiki 스타일) — 주로 틀 본문에서 `{{{파라미터}}}` 값에 따라 분기:
```
{{#if: 조건 | 참일때 | 거짓일때}}
조건이 (공백 제거 후) 비어있지 않으면 참, 비어있으면 거짓. 거짓일때 생략 가능.
{{#ifeq: A | B | 같을때 | 다를때}}
A==B 비교. 양쪽 숫자면 수치(1==1.0), 아니면 문자열.
{{#switch: 값 | 키1=결과1 | 키2=결과2 | #default=기본}}
값과 일치하는 첫 케이스 결과. 없으면 #default(또는 빈 문자열). 빈 키 케이스는 =결과.
```
※ 조건/비교 값은 그 시점의 문자열로 평가됨 — 다른 틀의 렌더 결과로는 분기 불가, `{{{파라미터}}}` 기준 분기가 표준. 코드블록/인라인코드 안의 `{{#...}}` 는 평가되지 않음.
### 아이콘
```
{bi:아이콘이름} Bootstrap Icons
{mdi:아이콘이름} Material Design Icons
```
### 각주
```
텍스트[* 각주 내용. **마크다운** 가능.]
```
### 펼치기/접기
```
[+ 버튼 제목]
숨겨진 내용 (마크다운 동작)
[-]
[+ {bg:#색상} {color:#색상} 커스텀 제목]
내용
[-]
```
### 헤딩 문단 접기
헤딩 끝에 `{collapse}` 를 붙이면 그 문단(헤딩 섹션)이 **기본 접힘** 상태로 렌더된다. 하위 헤딩까지 한 섹션으로 함께 접힘.
```
## 상세 설명 {collapse}
기본으로 접힌 내용. 제목 클릭 시 펼쳐짐.
```
- 토큰 `{collapse}` 는 목차(get_toc)·제목·검색 섹션 라벨·AI 읽기 어디에도 노출 안 됨 (제목의 일부로 인식되지 않아 위키 링크/섹션 참조에도 무영향).
- 헤딩 **맨 끝**(트레일링)에서만 동작. `## 개요 {collapse}` ✅ / `## {collapse} 개요` ❌
### 색상 · 팔레트
```
인라인 텍스트 (==...== 는 형식 캐리어 — 토큰 없는 단독 ==텍스트== 는 효과 없음):
{bg:yellow}==텍스트== ← 배경(형광펜)
{color:#FF0000}==텍스트== ← 글자색
{bg:#000}{color:#FFF}==텍스트== ← 배경+글자색
표 셀:
| {bg:red}{color:white} 내용 | ...
팔레트 프리셋: primary / secondary / success / info / warning / danger / muted
{palette:primary}
팔레트 뒤에 {bg:}/{color:} 붙이면 해당 속성 덮어쓰기 가능.
```
> ⚠ 배경/글씨 중 하나만 설정하면 다크 모드 가독성 문제가 생길 수 있으므로 둘 다 설정 권장.
### 글자 크기
```
{fs:xl}==큰 텍스트== ← 크기: xs / sm / lg / xl / xxl (기본 크기는 토큰 생략)
{fs:sm}{color:gray}==작은 부연== ← 색상/팔레트 토큰과 순서 무관 합성
{fs:xxl}{palette:primary}{badge:대형 배지} ← 인라인 컴포넌트(badge/tag/button/stat/kbd/progress)에도 적용
```
enum 밖 값(픽셀 등 자유 입력)은 무시됨.
### 타임스탬프
```
{dday:YYYY-MM-DD} 또는 {dday:MM-DD}
{age:YYYY-MM-DD}
{time:유닉스타임}
{timer:유닉스타임}
{calendar:YYYY-MM-DD} 또는 {calendar:MM-DD}
```
### 시점별 조건부 표시
```
:::until <시각> ← 시각 이전에만 표시
내용
:::
:::after <시각> ← 시각 이후에만 표시
내용
:::
시각: 유닉스초(전 세계 동일 순간) 또는 YYYY-MM-DD / YYYY-MM-DD HH:MM (뷰어 로컬 시간대)
```
- 표시 전용(엠바고 아님): 숨김 분기 원문도 검색·MCP raw 열람에 항상 노출됨.
- 헤딩 번호·`s-N.N` 앵커는 양쪽 분기를 모두 세어 시각과 무관하게 고정(섹션 링크 안정).
- 분기별로 다른 각주가 필요하면 분기마다 다른 이름/익명 각주 `[* 내용]` 사용(이름 있는 각주 정의는 문서 전역 공유 — 첫 정의 채택).
### 미디어 삽입
형식.
지원: YouTube, ニコニコ動画, Spotify, Google Maps.
바로 뒤 `{size:small|medium}` 토큰으로 임베드 최대 폭 제한 가능(small=420px, medium=640px, 가운데 정렬).생략 시 전체 폭.
---
## 3. 인라인 컴포넌트
모든 컴포넌트 기본 구조: `{[아이콘]}{[색상]}{컴포넌트:내용}`
```
{badge:텍스트} ← 배지 (기본 크기 칩)
{tag:텍스트} ← 태그 (소형 칩)
{stat:값|제목} ← 스탯 (제목+내용 칩)
{button:텍스트|URL} ← 링크 버튼
{kbd:Ctrl+S} ← 키보드 키 (+ 로 조합키)
{progress:70} ← 진행도 바 (0~100 또는 a/b)
{progress:7/10|라벨}
{hr} ← 인라인 가로선 (블록 내부 사용 가능)
{br} ← 줄바꿈 (표 셀/틀 인자/콜아웃/펼치기 제목 등 직접 줄바꿈 불가한 곳에서 사용, 코드블록 안에서는 그대로 출력)
```
색상 적용 예:
```
{palette:primary}{badge:텍스트}
{bi:star}{palette:warning}{stat:5|평점}
{color:#0f0}{progress:80|완료율}
```
---
## 4. 블록 컴포넌트 (:::지시어)
블록 내부에 다른 블록 중첩 가능. 단, `grid`/`row` 중첩은 비권장.
### 카드
```
:::card {palette:팔레트} 카드 제목
{palette:success}본문 내용
:::
```
### 콜아웃
타입: `info` / `tip` / `success` / `warning` / `danger` / `note`
```
:::info
안내 내용
:::
:::warning 커스텀 제목
주의 내용
:::
```
헤더 색 변경: `:::warning {palette:...} 제목` / 본문 색: 본문 첫 줄에 `{palette:...}` 추가.
### 임베드
```
:::embed 제목 {palette:reverse}
https://youtu.be/...
설명 텍스트
:::
:::embed
제목·색 생략 시 기본 강조선 박스
:::
```
### 그리드 / row / 캔버스
```
:::grid
인라인 컴포넌트들 또는 표 (옵션 없으면 화면 폭 반응형 자동 배치)
:::
그리드 옵션 (생략 가능, 모바일은 항상 1열로 접힘):
:::grid {cols:3} {gap:md} {align:start} ← cols:2~6 균등 열
:::grid {template:1-3} ← 비대칭 비율
template 프리셋: 1-1/1-2/2-1/1-3/3-1/1-1-1/1-2-1/2-1-1/1-1-2/1-1-1-1
또는 8-4 · 3-3-6 · 5-7 같은 임의 정수 비율(열 2~6개, 각 1~12)도 가능.
gap: sm|md|lg, align: start|center|stretch. cols 와 template 동시 지정 시 template 우선.
:::row
인라인 컴포넌트들 또는 표 (가로 스크롤 고정 배치)
:::
캔버스 = 12칸 기준 비대칭 자유 배치. 자식 :::area {span:N} (N=1~12, 한 줄 합 12 권장).
:::area 반응형 토큰: {span-md:1~12} 태블릿 폭에서의 칸 수 (예: 데스크톱 8/4 → 태블릿 12/12)
/ {order:1~9} 모바일 1열 접힘 시 표시 순서(미지정 영역이 먼저) / {sticky} 스크롤 시 상단 고정(모바일 해제).
:::area 줄에 {panel} 을 붙이면 카드형 여백·테두리(chrome) 적용:
:::canvas {gap:md}
:::area {span:8} {panel} {palette:primary}
주 콘텐츠 (색·{panel} 토큰은 본문이 아닌 :::area 줄에)
:::
:::area {span:4} {panel}
사이드 (span 생략 시 전체 폭)
:::
:::
```
### 탭
```
:::tabs
:::tab 탭1 {icon:bi-아이콘}
내용
:::
:::tab 탭2
내용
:::
:::
```
### 아코디언
```
:::accordion ← 단일 열림 모드 (기본)
:::accordion {multiple} ← 다중 열림 모드
:::item 제목 {open} {icon:bi-아이콘}
내용
:::
:::item 제목2
내용
:::
:::
```
### 스탭 (Steps)
```
:::steps
:::step 제목 {status:done}
내용
:::
:::step 제목 {status:current}
내용
:::
:::step 제목
내용 (기본 status: todo)
:::
:::
```
상태값: `done` (완료) / `current` (진행 중) / `todo` (미진행, 기본값)
### 정렬
타입: `left` / `center` / `right`. 문단·이미지·표·컴포넌트를 정렬하는 최소 컨테이너 (text-align + 블록 자식 margin:auto).
```
:::center
가운데 정렬할 문단 / 이미지 / 표 / 컴포넌트
:::
```
### 플로팅 패널 / 인포박스
본문이 옆을 감싸는 좌/우 고정 패널. 옵션: (기본 right), (12칸 기준 폭, 기본 4). 모바일에서는 float 해제 후 전체 폭 스택.
```
:::float {right} {span:4}
| 항목 | 값 |
| --- | --- |
| 출시 | 2007-08-31 |
:::
본문 문단은 패널 왼쪽을 감싸며 흐름…
```
인포박스 = float + 제목 헤더 + 카드 chrome 프리셋(나무위키식 프로필 상자). 제목 줄에 // 로 헤더 색 지정. 내부에서는 구분 행(| --- |) 없이 | 항목 | 값 | 행만 나열해도 표로 자동 승격됨.
```
:::infobox 하츠네 미쿠 {palette:primary}
| 발매일 | 2007-08-31 |
| 나이 | {age:2007-08-31} |
:::
```
틀 본문에 인포박스 + 를 넣으면 한 줄로 표준 인포박스 재사용 가능.
### 갤러리
이미지 균등 정사각 썸네일 그리드. 옵션: (기본 3, 모바일 항상 2열). 캡션 = alt 텍스트, 클릭 시 원본 새 탭. 이미지 외 내용은 무시.
```
:::gallery {cols:3}
:::
```
---
## 5. Mermaid 다이어그램
` FENCED_CODE_25 chart ` 코드펜스로 Chart.js 차트 렌더링. 라이트/다크 테마 자동 전환, 문법 오류 시 인라인 오류 박스만 표시(문서 안 깨짐).
키-값 DSL 만 지원(임의 JS 옵션 불가):
- type: bar | line | pie | doughnut | radar (필수)
- labels: [값, 값, ...] (필수)
- series: 다음 줄부터 들여쓰기로 `이름: [숫자, ...]` 나열 (1개 이상)
제약: 시리즈 최대 8개, pie/doughnut 항목(labels) 최대 8개, 각 시리즈 값 개수 = labels 개수.
````
```chart
type: bar
labels: [1Q, 2Q, 3Q, 4Q]
series:
매출: [120, 150, 170, 210]
이익: [20, 35, 40, 55]
```
````