Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 10. 18:08

Eleventy에서의 GEO 자동화: 수동 마크업 없는 JSON-LD, BLUF 및 테이블 구현

요약

Eleventy의 Nunjucks include와 shortcodes를 활용하여 JSON-LD, BLUF, HTML 테이블 등 GEO/SEO 요소를 자동화하는 방법을 설명합니다. 수동 마크업의 기술 부채를 해결하고 템플릿 기반의 일관된 데이터 구조를 구축하는 가이드를 제공합니다.

핵심 포인트

  • Nunjucks를 활용한 GEO 인프라 자동화 구현
  • JSON-LD 스키마(Article, FAQPage 등) 자동 생성
  • 프론트매터 기반의 데이터 일관성 유지
  • 수동 마크업 제거를 통한 기술 부채 방지

BLUF - GEO/SEO 2026 시리즈의 Part 3

  • 문제점: 모든 포스트에 대해 JSON-LD, BLUF 블록, HTML 테이블을 수동으로 작성하는 것은 시간이 많이 소요되며 오류가 발생하기 쉽습니다.
  • 해결책: Eleventy의 Nunjucks include 및 shortcodes를 활용합니다. 템플릿을 한 번 설정해 두면, 모든 새 포스트는 프론트매터 (frontmatter)로부터 자동으로 전체 GEO 인프라를 부여받습니다.
  • 자동화 대상: Article Schema, FAQPage Schema, HowTo Schema, BLUF 블록, data-label이 포함된 HTML 테이블, 그리고 robots.txt.
  • 설정 시간: 최초 1.5~2시간 소요 → 이후 포스트당 0분 소요.
  • Part 1: GEO 기술 아키텍처: robots.txt, JSON-LD, 그리고 시맨틱 HTML (Semantic HTML)
  • Part 2: LLM을 위한 콘텐츠 엔지니어링: 정보 밀도와 BLUF 구조

수동 마이크로 마크업 (Micro-Markup)이 확장 불가능한 이유

Part 1에서는 각 스키마 (Schema) 유형에 대해 JSON-LD를 수동으로 작성했습니다. Part 2에서는 각 포스트에 BLUF 블록과 HTML 테이블을 개별적으로 추가했습니다. 포스트가 5개뿐인 블로그라면 허용 가능한 수준입니다. 하지만 포스트가 50개가 되면 이는 기술 부채 (technical debt)가 되어 데이터 불일치를 보장하게 됩니다. 어떤 포스트에는 FAQPage Schema가 누락되고, 다른 포스트에는 오래된 저자 URL이 포함되며, 세 번째 포스트에는 BLUF가 없는 식입니다.

올바른 해결책은 다음과 같습니다: 템플릿에서 한 번만 변경하면 = 모든 포스트에 동시에 업데이트가 적용됩니다.

Step 1. 기본 구성: _data/metadata.json

모든 Nunjucks 템플릿은 여기서 전역 사이트 데이터를 가져옵니다. 파일이 이미 존재한다면, 다음 필드들이 포함되어 있는지 확인하십시오:

{
  "title": "Your Blog Title",
  "description": "A technical blog about development and AI tools",
...

Step 2. Article Schema - 모든 포스트에 자동 적용

_includes/schema-article.njk를 생성합니다. 이 파일은 현재 페이지의 프론트매터 (frontmatter)에서 title, description, date, thumbnail을 읽어 유효한 JSON-LD를 생성합니다:

{% raw %}{%- if title and page.url -%}
<script type="application/ld+json">
{
...

.eleventy.js의 dateToISO 필터

Eleventy에는 내장된 ISO 필터가 없습니다. .eleventy.js에 다음을 추가하십시오:

module.exports = function(eleventyConfig) {

  // 필터: Date → JSON-LD를 위한 ISO 8601 문자열
...

기본 레이아웃에 추가하기

_includes/base.njk 또는 _includes/layouts/post.njk 파일의 <head> 블록 내부에 다음을 추가합니다:

{% raw %}<head>
  <meta charset="UTF-8">
  <title>{{ title }} | {{ metadata.title }}</title>
...

이제 모든 새로운 포스트에는 추가적인 노력 없이도 Article Schema (기사 스키마)가 자동으로 적용됩니다.

3단계. Frontmatter 배열을 통한 FAQPage Schema 구현

핵심 아이디어: FAQ 질문과 답변을 포스트의 Frontmatter (프론트매터)에 직접 정의합니다. 템플릿이 Schema (스키마)를 자동으로 생성하며, 동일한 데이터가 페이지의 HTML FAQ 섹션을 렌더링합니다.

Frontmatter 구조

---
title: "포스트 제목"
faq:
...

템플릿 _includes/schema-faq.njk

{% raw %}{%- if faq and faq.length -%}
<script type="application/ld+json">
{
...

동일한 데이터를 사용하여 FAQ 섹션 렌더링하기

포스트 템플릿 내의 (<head>가 아닌 <body> 블록에) 다음을 추가합니다:

{% raw %}{%- if faq and faq.length -%}
<section>
  <h2>Frequently Asked Questions</h2>
...

하나의 Frontmatter 배열로 Google/AI를 위한 Schema (스키마)와 독자를 위한 HTML을 모두 생성합니다. 데이터 동기화가 보장됩니다.

4단계. 단계별 가이드를 위한 HowTo Schema

가이드 포스트의 Frontmatter에 다음을 추가합니다:

howto:
  name: "How to Set Up SSH Deployment"
  totalTime: "PT1H"
...

템플릿 _includes/schema-howto.njk

{% raw %}{%- if howto and howto.steps -%}
<script type="application/ld+json">
{
...

5단계. 자동 BLUF 블록

매 포스트마다 BLUF (핵심 요약)를 수동으로 작성하는 대신, 불렛 포인트를 Frontmatter 배열인 bluf로 옮기고 템플릿이 이를 렌더링하도록 합니다.

Frontmatter

bluf:
  - "**Goal:** automate GEO markup so we never write JSON-LD by hand."
  - "**Time:** 2 hours of setup, then 0 minutes per new post."
...

템플릿 _includes/bluf.njk

{% raw %}{%- if bluf and bluf.length -%}
<div class="tldr">
  <div class="tldr-title">BLUF - Summary for AI Crawlers</div
...

이를 포스트 템플릿의 최상단, <h1 바로 다음에 포함시키세요:

{% raw %}<article>
{# H1은 레이아웃을 통해 frontmatter title에서 렌더링됩니다 - 중복하지 마세요 #}
{% include "bluf.njk" %}
...
{% endraw %}

markdownify 필터

// .eleventy.js - frontmatter 문자열 내의 인라인 마크다운(markdown)을 렌더링합니다
const markdownIt = require("markdown-it");
const md = new markdownIt({ html: true });
...

단계 6. GEO 테이블을 위한 Shortcode (숏코드)

매번 모든 data-label 속성을 포함하여 <table을 수동으로 작성하는 대신, .eleventy.js에 하나의 숏코드(shortcode)를 정의하고 Markdown에서 깔끔한 파이프 구분(pipe-separated) 구문을 사용하세요.

.eleventy.js에서 숏코드 등록하기

// Paired shortcode (쌍을 이루는 숏코드): {% geotable "Header 1,Header 2,Header 3" %}
// 데이터 행: Value 1 | Value 2 | Value 3
// {% endgeotable %}
...

Markdown 포스트에서의 사용법

{% raw %}{% geotable "Platform,TTFB,Price/mo,Control" %}
Eleventy + NVMe VPS | <50 ms  | $5-10 | Full
WordPress (shared)  | 800+ ms | $9    | Limited
...

이 숏코드는 모든 셀에 data-label을 자동으로 추가하므로, 추가적인 변경 없이도 모바일 CSS 카드 변환(card transformation)이 작동합니다.

단계 7. robots.txt 자동 생성

정적 파일 대신, metadata.json에서 사이트 URL을 자동으로 대체하는 Nunjucks 템플릿을 사용합니다.

프로젝트 루트에 robots.njk를 생성하세요:

---
permalink: /robots.txt
eleventyExcludeFromCollections: true
...

Eleventy는 이를 _site/robots.txt로 자동 빌드합니다. metadata.json에서 사이트 URL이 변경되면, Sitemap(사이트맵) 라인이 모든 곳에서 한 번에 업데이트됩니다.

요약: 자동화된 항목 및 설정 시간

요소이전 (수동)자동화 이후설정 시간
Article Schema (기사 스키마)모든 포스트에 약 20줄 작성frontmatter로부터 자동 생성20분
...
총 설정 시간: 약 1.5~2시간. 그 이후에는 새 포스트를 작성할 때 수동 마크업 작업이 필요 없습니다.

구현 체크리스트

설정이 완료되었다고 판단하기 전에 각 항목을 확인하세요:

  • _data/metadata.json에 url, author, logo가 포함되어 있음
  • dateToISO 필터가 .eleventy.js에 등록됨
  • markdownify 필터가 .eleventy.js에 등록됨
  • _includes/schema-article.njk가 <head> 내부의 베이스 레이아웃(base layout)에 포함됨
  • _includes/schema-faq.njk가 베이스 레이아웃에 포함됨
  • _includes/schema-howto.njk가 베이스 레이아웃에 포함됨
  • _includes/bluf.njk가 포스트 템플릿의 H1 바로 다음에 포함됨
  • geotable 쇼트코드(shortcode)가 .eleventy.js에 등록됨
  • permalink: /robots.txt가 설정된 robots.njk 파일이 프로젝트 루트에 있음
  • 새 템플릿으로 첫 번째 포스트를 배포한 후 Google Rich Results Test를 통해 검증함

FAQ

이 방식은 Eleventy v2.x와 v3.x 모두와 호환되나요?

네. 모든 템플릿과 쇼트코드(shortcode)는 Eleventy v2.x 및 v3.x를 위해 작성되었습니다. addFilter, addPairedShortcode, addShortcode API는 버전 간에 변경되지 않았습니다. markdownify 필터는 해당 패키지가 의존성(dependencies)에 이미 포함되어 있지 않다면 npm install markdown-it을 통해 설치해야 합니다.

| dump | safe가 JSON-LD의 특수 문자를 올바르게 이스케이프(escape) 하나요?

네. Nunjucks의 dump 필터는 문자열을 유효한 JSON으로 직렬화(serialize)하여 따옴표, 백슬래시 및 특수 문자를 이스케이프합니다. | dump | safe 조합은 Nunjucks를 통해 JSON-LD에 동적 문자열을 삽입하는 표준 패턴입니다.

배포 후 Schema가 올바르게 생성되었는지 어떻게 확인하나요?

세 가지 도구가 있습니다: Google Rich Results Test - Article, FAQPage, HowTo를 검증합니다. Schema Markup Validator - 확장된 검증을 제공합니다. Bing Webmaster Tools → "URL inspection" - Copilot이 마크업을 어떻게 인식하는지 보여줍니다.

동일한 방식을 BreadcrumbList Schema에도 사용할 수 있나요?

네, 가능합니다. {% if series and order %} 조건문이 포함된 _includes/schema-breadcrumb.njk 파일을 추가하고 프론트매터 (frontmatter)에서 값을 가져오도록 설정하세요. 이는 시리즈 게시물에 특히 유용합니다. AI 검색 엔진이 각 파트 간의 관계를 파악하여 전체 클러스터 (cluster)의 권위 (authority)를 높여주기 때문입니다.

다음 단계: 파트 4

파트 4 - GEO 효과 측정하기: ChatGPT Search, Perplexity, 그리고 Gemini가 귀하의 사이트를 인용하고 있는지 체계적으로 추적하는 방법, 기존의 유기적 클릭률 (organic CTR)을 대체하는 지표는 무엇인지, 그리고 유료 도구 없이 curl, Python, Google Sheets만을 사용하여 모니터링 대시보드를 구축하는 방법을 다룹니다.

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0