Hugo 공식 숏코드 렌더링 테스트

이 페이지는 Hugo의 공식 내장 숏코드가 프론트엔드에서 어떻게 렌더링되는지 확인하기 위한 테스트 포스트다.

목표는 단순하다.

1. 각 숏코드가 깨지지 않고 출력되는지 확인한다.
2. Markdown 문맥과 HTML 문맥이 섞여도 레이아웃이 유지되는지 확인한다.
3. 중첩, 링크, 코드 하이라이트, 임베드, QR 생성 같은 대표 케이스를 한 번에 점검한다.
4. 각 렌더 결과 아래에서 실제 사용한 숏코드 원문도 함께 확인한다.

검증 대상

Hugo가 공식적으로 제공하는 내장 숏코드는 다음과 같다.

이 페이지는 위 요소를 각각 단독으로도 보고, 서로 조합했을 때도 보이는지 확인하도록 설계했다.

렌더링 체크 포인트

• 접기 블록 안에서 목록, 문단, 링크가 자연스럽게 이어지는가
• figure가 본문 흐름을 끊지 않고 캡션과 함께 배치되는가
• 코드 하이라이트가 테마 스타일과 충돌하지 않는가
• 외부 임베드가 iframe 또는 대체 마크업으로 안전하게 출력되는가
• ref / relref가 실제 페이지 링크로 바뀌는가
• param이 설정값을 정확하게 읽어오는가
• qr 이미지가 정상 생성되는가
• 중첩 숏코드가 문맥을 망가뜨리지 않는가

공통 테스트 예시

1) details

details는 펼침/접힘 UI를 확인하기 좋다. 내부에 일반 Markdown이 들어가도 레이아웃이 유지되어야 한다.

{{< details summary="details 테스트 보기" >}}
- 목록 항목 A
- 목록 항목 B
- `inline code`
- [현재 페이지 보기]({{< relref path="/blog/theme-upgrade-lab/03-rendering/shortcode-hugo" >}})

문단도 하나 더 넣어 본다. 접기 영역 안에서도 문단 간격이 자연스러워야 한다.
{{< /details >}}

2) figure

figure는 이미지, 대체 텍스트, 캡션, 링크가 한 번에 잘 나오는지 확인한다.

{{< figure src="https://placehold.co/1200x675/png?text=Hugo+Shortcode+Figure+Test" alt="숏코드 렌더링 테스트 이미지" title="figure 렌더링 테스트" caption="캡션이 이미지 아래에서 자연스럽게 이어져야 한다." class="w-100" loading="lazy" >}}

설명 문단은 figure 아래에서 바로 이어져야 한다.

3) highlight

highlight는 코드 블록이 테마 스타일과 함께 잘 보이는지 확인한다.

{{< highlight go "linenos=table,hl_lines=2 4,style=github" >}}
package main

import "fmt"

func main() {
    fmt.Println("Hugo shortcode test")
}
{{< /highlight >}}

1
2
3
4
5
6
7

package main

import "fmt"

func main() {
fmt.Println("Hugo shortcode test")
}

4) param

param은 설정값을 본문에 주입할 때 유용하다. 아래 예시는 front matter 값을 읽는 형태를 테스트한다.

- 설명 값: {{< param "description" >}}
- 제목 값: {{< param "title" >}}

• 설명 값: Hugo가 공식 지원하는 내장 숏코드의 렌더링을 한 페이지에서 점검하기 위한 샘플 포스트다.
• 제목 값: Hugo 공식 숏코드 렌더링 테스트

5) qr

qr은 텍스트를 QR 코드로 바꾸는지 확인한다.

{{< qr text="https://gohugo.io" >}}

아래처럼 본문에 넣는 방식도 함께 확인할 수 있다.

{{< qr >}}
https://gohugo.io
{{< /qr >}}

6) ref / relref

이 두 숏코드는 링크 생성이 정확한지 확인할 때 중요하다. 아래 예시는 현재 페이지 자체를 참조해서, 존재하지 않는 경로 때문에 빌드가 실패하는 상황을 피하도록 구성했다.

- 절대 참조: [현재 페이지]({{< ref "/blog/theme-upgrade-lab/03-rendering/shortcode-hugo" >}})
- 상대 참조: [현재 페이지]({{< relref path="/blog/theme-upgrade-lab/03-rendering/shortcode-hugo" >}})

• 절대 참조: 현재 페이지
• 상대 참조: 현재 페이지

7) instagram

실제 게시물 ID로 바꿔 넣어야 하는 테스트다.

{{< instagram CxOWiQNP2MO >}}

View this post on Instagram

8) vimeo

실제 비디오 ID로 바꿔 넣어야 한다.

{{< vimeo 19899678 >}}

9) x

X 포스트 임베드가 테마 내에서 안전하게 출력되는지 확인한다.

{{< x user="SanDiegoZoo" id="1453110110599868418" >}}

Owl bet you'll lose this staring contest 🦉 pic.twitter.com/eJh4f2zncC

— San Diego Zoo Wildlife Alliance (@sandiegozoo) October 26, 2021

10) youtube

YouTube 임베드가 반응형 영역 안에서 깨지지 않는지 확인한다.

{{< youtube 0RKpf3rK57I >}}

중첩 조합 테스트

공식 숏코드는 서로 조합해서 써도 되어야 한다. 아래 예시는 접기 안에 figure와 링크를 넣는 구성이다.

{{< details summary="중첩 조합 테스트" >}}

{{< figure src="https://placehold.co/1200x675/png?text=Nested+Shortcode+Test" alt="중첩 숏코드 테스트 이미지" caption="figure가 details 내부에서도 안정적으로 보이는지 확인한다." loading="lazy" >}}

- 내부 목록
- [현재 페이지 보기]({{< relref path="/blog/theme-upgrade-lab/03-rendering/shortcode-hugo" >}})
- `shortcode nesting`

{{< /details >}}

운영 메모

이 페이지는 내용 자체보다 렌더링 결과가 중요하다.

각 섹션에 붙은 코드블록은 프론트엔드에서 실제로 사용된 입력을 그대로 보여준다. 그래서 디자인 확인뿐 아니라, 복사해서 다른 페이지에 재사용할 때도 바로 참고할 수 있다.

체크할 때는 다음 순서가 효율적이다.

1. 본문이 깨지지 않는가
2. 여백과 줄바꿈이 맞는가
3. 임베드가 반응형으로 보이는가
4. 링크가 올바른 경로로 이동하는가
5. 다국어/테마 전환 후에도 결과가 유지되는가

마무리

이 포스트는 Hugo 내장 숏코드의 기본 동작을 한 번에 확인하기 위한 기준 페이지다.

새 테마를 적용했거나 레이아웃을 손봤다면, 이 페이지를 기준으로 내장 숏코드 렌더링과 링크 동작을 함께 확인하면 된다.