Cloudwiki/위키 문법 가이드/고급 예시

이 문서는 [[Cloudwiki/위키 문법 가이드]] 와 [[Cloudwiki/위키 문법 가이드/컴포넌트]] 에서 개별적으로 다루는 문법들을 **서로 조합**하는 실전 예시를 모았습니다. 개별 문법의 정의·옵션은 그 두 문서에서, 이 문서는 "무엇을 무엇과 함께 쓰는가"를 봅니다.

예시는 **조합하는 기능 유형별**로 묶여 있으며, 각 절은 실제로 화면에 표시되는 결과를 먼저 보여주고 이어서 복사용 원본 문법을 코드 블록으로 제시합니다.

정보:
이 페이지의 모든 예시는 실제로 화면에 표시되는 결과입니다. 문법을 복사할 때는 각 예시 아래의 코드 블록을 사용하세요.


# 칩·타임스탬프·아이콘 조합

인라인 칩에 타임스탬프·아이콘·색을 겹쳐 하나의 표현으로 합칩니다.

## 칩 값에 타임스탬프 넣기

`{stat:}` · `{badge:}` · `{tag:}` 같은 칩의 **값 안에** `{dday:}` · `{age:}` 같은 타임스탬프 토큰을 그대로 넣을 수 있습니다. 칩의 값은 중괄호의 짝을 맞춰 인식하므로 값 안의 `{...}` 토큰이 칩을 깨뜨리지 않고, `{palette:}` · `{bi:}` · `{fs:}` 를 앞에 이어 붙여 색·아이콘·크기를 함께 지정합니다.


[
[마감 



```
{palette:primary}{stat:{dday:2026-03-09}|콘서트까지}
{palette:success}{badge:{age:2007-08-31}세}
{palette:info}{tag:마감 {dday:03-31}}
{bi:calendar-event}{palette:warning}{stat:{dday:12-25}|크리스마스}
{fs:xl}{bi:cake2}{palette:danger}{stat:{dday:08-31}|미쿠 생일}
```

>  타임스탬프는 5종(`dday` · `age` · `time` · `timer` · `calendar`)이며, 형식은 [[Cloudwiki/위키 문법 가이드]] 의 *타임스탬프* 절을 참고하세요.

# 링크·내비게이션

버튼·앵커로 문서 안팎을 잇고, 접혀 있는 항목으로 바로 이동합니다.

## 내부 링크 버튼

버튼의 링크 자리에 URL 대신 위키 링크 `[[문서]]` 를 넣으면, 외부 링크 확인 팝업 없이 위키 문서로 바로 이동하는 **내부 링크 버튼**이 됩니다. `#섹션` 앵커도 함께 지정할 수 있습니다.

[문법 가이드 홈]([[Cloudwiki/위키 문법 가이드]])
[컴포넌트 문서]([[Cloudwiki/위키 문법 가이드/컴포넌트]])

```
{palette:primary}{button:문법 가이드 홈|[[Cloudwiki/위키 문법 가이드]]}
{bi:puzzle}{palette:info}{button:컴포넌트 문서|[[Cloudwiki/위키 문법 가이드/컴포넌트]]}
```

>  `{button:텍스트|[[문서#섹션|라벨]]}` 처럼 링크에 라벨을 함께 적어도, 버튼에는 앞의 *텍스트* 가 표시됩니다.

## 탭·아코디언 딥링크 ()

탭·아코디언 항목 제목에 `{id:이름}` 을 붙이면 그 항목에 안정적인 앵커가 생깁니다. `[[문서#이름]]` 링크(위 *내부 링크 버튼* 포함)로 이동하면 접혀 있던 항목이 자동으로 펼쳐지며 스크롤됩니다. 이름은 영문·숫자·`_`·`-` 만 사용합니다.


설치하기 
`npm install` 로 의존성을 설치합니다.

문제 해결 
캐시를 지우고 다시 시도하세요. 이 항목은 아래 버튼으로 바로 열 수 있습니다.



[문제 해결 항목 열기]([[Cloudwiki/위키 문법 가이드/고급 예시#troubleshoot]])

```
:::accordion
:::item 설치하기 {id:install}
`npm install` 로 의존성을 설치합니다.
:::
:::item 문제 해결 {id:troubleshoot}
캐시를 지우고 다시 시도하세요.
:::
:::

{palette:primary}{bi:arrow-down-circle}{button:문제 해결 항목 열기|[[Cloudwiki/위키 문법 가이드/고급 예시#troubleshoot]]}
```

# 시점 분기 활용

`:::until` / `:::after` 로 특정 시각을 경계로 내용을 바꾸고, 카운트다운·진행도 등과 결합합니다.

## 시점 전환 구성 (:::until / :::after)

`:::until 시각` / `:::after 시각` 블록은 안에 카드·칩·타임스탬프 같은 다른 문법을 그대로 담을 수 있습니다. 같은 경계 시각으로 두 블록을 쌍으로 두면, 시점 전에는 카운트다운을, 시점 후에는 공개 내용을 보여주는 전환 구성이 됩니다. 페이지를 열어둔 채 시각을 지나도 자동으로 전환됩니다.

2030-01-01
공개 예정


2030년 1월 1일 0시(보는 기기의 시간대 기준)에 이 자리의 내용이 자동으로 바뀝니다.


2030-01-01
공개 완료
공개되었습니다! 이 카드는 2030년 1월 1일 이후에만 보입니다.



```
:::until 2030-01-01
:::card {palette:primary} 공개 예정
{bi:calendar-event}{palette:primary}{stat:{dday:2030-01-01}|공개까지}

2030년 1월 1일 0시(보는 기기의 시간대 기준)에 이 자리의 내용이 자동으로 바뀝니다.
:::
:::
:::after 2030-01-01
:::card {palette:success} 공개 완료
공개되었습니다! 이 카드는 2030년 1월 1일 이후에만 보입니다.
:::
:::
```

>  유닉스 초(예: `:::after 1893456000`)는 전 세계가 동일한 순간에, `YYYY-MM-DD[ HH:MM]` 은 보는 사람의 기기 시간대 기준으로 전환됩니다. **표시 전용 기능**이므로 숨겨진 분기의 원문도 검색·AI 문서 열람에는 노출됩니다 — 정해진 시각까지 내용을 감추는 용도로는 쓰지 마세요.

## 시점 분기와 자동 진행도

`{progress:auto}` 는 숨겨진 시점 분기 안의 체크박스를 집계에서 제외하고, 경계 시각을 지나 분기가 나타나면 자동으로 다시 계산합니다. 시점이 지나면 다음 단계 항목이 열리는 체크리스트를 만들 수 있습니다.

프로젝트 체크리스트
- [x] 기획
- [x] 구현

2030-01-01
- [ ] 회고 작성
- [ ] 차기 계획 수립


진행도: auto


```
:::card {palette:info} 프로젝트 체크리스트
- [x] 기획
- [x] 구현

:::after 2030-01-01
- [ ] 회고 작성
- [ ] 차기 계획 수립
:::

{progress:auto|진행도}
:::
```

>  2030년 1월 1일 전에는 `2/2 · 100%`, 이후에는 항목이 늘어 `2/4 · 50%` 로 자동 갱신됩니다. `{progress:auto}` 를 시점 블록 **안에** 두면 그 분기 내부만 집계합니다.

# 데이터·자동 계산

값을 한곳에서 정의하고, 계산·조건·집계로 문서를 자동 갱신합니다.

## 문서 변수 (:::meta)

`:::meta` 블록에 `이름 = 값` 을 정의하면, 문서 어디서든 `{{{@이름}}}` 으로 그 값을 불러올 수 있습니다. 반복되는 값을 한곳에서 관리할 때 유용하며, 여기서 정의한 값은 아래 *조건 분기 틀* · *실전 조합* · *대시보드* 예시에서 그대로 재사용합니다. `:::meta` 블록 자체는 출력에 표시되지 않습니다.


프로젝트 = Cloudwiki
버전 = 2.0
목표 = 100
완료 = 73
등급 = A


**** 위키의 현재 버전은  입니다.

```
:::meta
프로젝트 = Cloudwiki
버전 = 2.0
:::

**{{{@프로젝트}}}** 위키의 현재 버전은 {{{@버전}}} 입니다.
```

>  `{{{@이름}}}` 은 `@` 접두가 붙은 문서 변수 전용입니다. `@` 없는 `{{{이름}}}` 은 틀 파라미터로 그대로 남습니다.

## 계산식 ()

`{{#expr: 식}}` 은 기본적인 사칙연산을 계산해 결과 숫자를 보여줍니다. `+ - * /` 와 괄호, 음수 부호, 그리고 `round` · `floor` · `ceil` 함수를 지원합니다.

- 2 + 3 × 4 = 
- (10 − 4) ÷ 2 = 
- round(10 ÷ 3) = 
- floor(10 ÷ 3) = 
- ceil(10 ÷ 3) = 

```
- 2 + 3 × 4 = {{#expr: 2 + 3 * 4}}
- (10 − 4) ÷ 2 = {{#expr: (10 - 4) / 2}}
- round(10 ÷ 3) = {{#expr: round(10 / 3)}}
- floor(10 ÷ 3) = {{#expr: floor(10 / 3)}}
- ceil(10 ÷ 3) = {{#expr: ceil(10 / 3)}}
```

## 자동 진행도 집계

`{progress:auto}` 는 같은 블록(카드·콜아웃·펼치기·탭 패널·시점 블록·섹션 등) 안의 체크리스트 완료율을 자동으로 계산해 진행도 바를 채웁니다. 체크 항목을 늘리거나 완료 표시만 바꾸면 값이 따라 갱신됩니다.

오늘 할 일
- [x] 이메일 확인
- [x] 회의 참석
- [ ] 보고서 작성
오늘 진행도: auto


```
:::card {palette:success} 오늘 할 일
- [x] 이메일 확인
- [x] 회의 참석
- [ ] 보고서 작성
{progress:auto|오늘 진행도}
:::
```

>  라벨을 생략하고 `{progress:auto}` 만 써도 됩니다. 완료율만 막대로 표시됩니다.

>  집계 범위는 **가장 가까운 상위 블록**입니다. 탭 패널·아코디언 항목·카드 안에 두면 그 블록의 체크리스트만 세고, 어떤 블록에도 속하지 않으면 문서 전체를 집계합니다.

## 조건 분기 틀 (조건문)

조건문 `{{#if:}}` · `{{#ifeq:}}` · `{{#switch:}}` 는 값에 따라 출력을 다르게 만듭니다. 주로 틀 본문에서 `{{{파라미터}}}` 로 분기하지만, 위 *문서 변수* 의 `{{{@변수}}}` 와 결합하면 일반 문서에서도 값 하나로 배지·태그를 바꿀 수 있습니다. 아래는 `등급 = {{{@등급}}}` 에 따라 결과가 달라지는 예시입니다.

- 등급 배지: 
- 최상위 여부: 
- 완료 기록: 

```
{{#switch: {{{@등급}}}
| S = {palette:danger}{badge:S · 최상위}
| A = {palette:warning}{badge:A · 상위}
| #default = {palette:secondary}{badge:일반}
}}
{{#ifeq: {{{@등급}}} | S | 최상위 확정 | 승급 가능 }}
{{#if: {{{@완료}}} | 완료 {{{@완료}}}건 기록됨 | 기록 없음 }}
```

>  틀 본문에서는 `{{{@등급}}}` 대신 `{{{등급|}}}` 처럼 **틀 파라미터**로 분기합니다. 조건 값은 화면에 표시되는 시점의 글자(텍스트)를 그대로 비교하며, 다른 틀이 만들어 낸 결과를 조건으로 삼을 수는 없습니다.

# 콘텐츠 재사용

다른 문서·섹션·각주를 끌어와 중복 없이 재사용합니다.

## 섹션 단위 틀

`{{문서#섹션}}` 은 다른 문서 전체가 아니라 특정 섹션만 현재 문서로 가져옵니다. 섹션은 목차 번호(`#s-1.2` 또는 `#1.2`) 또는 헤딩 제목(`#제목`)으로 지정합니다.

아래는 [[Cloudwiki/위키 문법 가이드/컴포넌트]] 문서의 *키보드 키* 절만 가져온 결과입니다.



```
{{문서명#s-1.2}}       ← 섹션 번호 (s- 접두)
{{문서명#1.2}}         ← 섹션 번호 (접두 없이)
{{문서명#제목}}        ← 헤딩 제목 그대로
{{문서명#제목|키=값}}  ← 섹션에 파라미터 전달
```

>  소스 문서가 헤딩을 만들어내는 틀을 섹션 앞에 포함하면 목차 번호가 어긋날 수 있습니다. 이런 경우 번호 대신 **헤딩 제목** 으로 지정하면 안정적으로 동작합니다.

>  대상 섹션이 `{{{파라미터}}}` 를 사용하면 `{{문서#섹션|키=값}}` 으로 값을 넘길 수 있습니다 — 문서 전체를 부르는 틀 파라미터와 동일하게 동작합니다.

## 이름 있는 각주

기존 익명 각주 `[* 내용]` 에 더해, 각주에 이름을 붙여 문서 여러 곳에서 같은 각주를 재사용할 수 있습니다. `[*이름 내용]` 으로 한 번 정의하고, 같은 이름을 `[*이름]` 으로 참조하면 같은 번호를 공유하며, 본문의 각주 표시에 `a`·`b`·`c` 같은 되돌아가기 링크가 붙습니다.

하츠네 미쿠[*미쿠 크립톤 퓨처 미디어가 2007년에 발매한 소프트웨어 음원이자 캐릭터입니다.]는 대표적인 보컬로이드입니다. 미쿠[*미쿠]의 데뷔일을 기준으로 한 나이는  입니다.

```
하츠네 미쿠[*미쿠 크립톤 퓨처 미디어가 2007년에 발매한 소프트웨어 음원이자 캐릭터입니다.]는 대표적인 보컬로이드입니다. 미쿠[*미쿠]의 데뷔일을 기준으로 한 나이는 {age:2007-08-31} 입니다.
```

>  이름에는 한글·영문·숫자·`.`·`-` 등을 쓸 수 있습니다. 정의(`[*이름 내용]`)는 문서에 한 번만 두고, 나머지는 참조(`[*이름]`)로 적습니다.

>  이름 있는 각주 정의는 시점 분기(`:::until`/`:::after`) 안에 있어도 문서 전역에서 공유됩니다(첫 정의 채택). 분기마다 다른 내용의 각주가 필요하면 분기별로 서로 다른 이름 또는 익명 각주 `[* 내용]` 을 사용하세요.

# 종합 실전

앞의 기능들을 한곳에 모아 값 하나로 갱신되는 실전 요약·대시보드를 구성합니다.

## 실전 조합: 요약 카드

`:::meta` · `{{#expr:}}` · `{progress:auto}` 를 함께 쓰면, 값 하나만 바꿔도 요약이 통째로 갱신되는 카드를 만들 수 있습니다. 아래 값은 *문서 변수* 절에서 정의한 `:::meta` 에서 그대로 가져옵니다.

 스프린트 현황
전체 개 중 개 완료 — 달성률 %, 남은 작업 개.

- [x] 기획
- [x] 설계
- [x] 구현
- [ ] 배포
스프린트 진행도: auto


```
:::card {palette:primary} {{{@프로젝트}}} 스프린트 현황
전체 {{{@목표}}}개 중 {{{@완료}}}개 완료 — 달성률 {{#expr: round({{{@완료}}} / {{{@목표}}} * 100)}}%, 남은 작업 {{#expr: {{{@목표}}} - {{{@완료}}}}}개.

- [x] 기획
- [x] 설계
- [x] 구현
- [ ] 배포
{progress:auto|스프린트 진행도}
:::
```

## 대시보드: 그리드 + 스탯 + 진행도

`:::grid` 로 스탯 카드를 나란히 배치하고, 각 스탯 값에 `:::meta` 변수와 `{{#expr:}}` 계산을 넣은 뒤, 아래 카드에서 `{progress:auto}` 로 체크리스트를 집계하면 블록 단위 대시보드가 됩니다. 역시 값은 *문서 변수* 절의 `:::meta` 에서 가져옵니다.


완료
{{}|건}

목표
{{}|건}

달성률
%



 대시보드
- [x] 기획
- [x] 설계
- [x] 구현
- [ ] 배포
전체 진행도: auto


```
:::grid {cols:3} {gap:md}
:::card {palette:primary} 완료
{stat:{{{@완료}}}|건}
:::
:::card {palette:info} 목표
{stat:{{{@목표}}}|건}
:::
:::card {palette:success} 달성률
{stat:{{#expr: round({{{@완료}}} / {{{@목표}}} * 100)}}%}
:::
:::

:::card {palette:primary} {{{@프로젝트}}} 대시보드
- [x] 기획
- [x] 설계
- [x] 구현
- [ ] 배포
{progress:auto|전체 진행도}
:::
```

>  스탯 값 안의 `{{{@완료}}}` · `{{#expr:}}` 는 스탯이 화면에 그려지기 전에 먼저 값이 채워지고 계산되므로, `:::meta` 값만 바꾸면 카드 세 개가 한꺼번에 갱신됩니다.

---

전체 문법 목록은 [[Cloudwiki/위키 문법 가이드]] 와 [[Cloudwiki/위키 문법 가이드/컴포넌트]] 를 참고하세요.