HTML 필수 가이드: 워드프레스 테마 마크업과 시맨틱 구조

한눈에 보기: 워드프레스 HTML은 테마의 가독성·접근성·SEO를 결정합니다. 시맨틱 태그(header/nav/main/article/section/footer), 헤딩 구조(H1→H2), 접근성(스크린 리더·키보드), 블록 에디터(Gutenberg) 마크업, 이미지 최적화(srcset·lazy), 구조화 데이터까지 이해하면 테마 품질이 한 단계 올라갑니다.

1. 워드프레스와 HTML: 테마 마크업의 역할

워드프레스는 데이터를 PHP로 가공해 최종적으로 HTML을 출력합니다. 사용자는 HTML을 보고 상호작용하므로, 마크업 품질이 곧 UX와 SEO 성과로 이어집니다. 코드가 복잡해질수록 HTML의 역할은 더 중요해집니다.

테마는 템플릿 파일에서 Loop를 통해 글 목록·단일 글·페이지를 HTML로 구성합니다. 이때 시맨틱 태그를 정확히 쓰면 검색엔진과 보조공학이 문서 구조를 올바르게 이해합니다. 반대로 의미 없는 <div> 남용은 인덱싱과 접근성에 불리합니다.

마크업은 “디자인이 아니라 의미”를 표현합니다. 스타일은 CSS가, 인터랙션은 JS가 담당하므로 역할 분리가 뚜렷할수록 유지보수가 쉬워집니다.

핵심 요약: 테마의 성공은 HTML 의미론에서 시작합니다. 의미 → 스타일 → 인터랙션 순서를 지키세요.

2. 시맨틱 태그로 뼈대 세우기

페이지 공통 레이아웃은 <header>, <nav>, <main>, <aside>, <footer>로 구성합니다. 메인 콘텐츠는 문서당 하나의 <main>만 사용해 스크린 리더가 빠르게 이동할 수 있게 합니다.

글 단위에는 <article>을, 그룹에는 <section>을 사용합니다. <section>은 주제별 구획이라는 뜻이므로, 제목이 없다면 <div>가 더 적합할 수 있습니다.

내비게이션은 <nav>로 감싸고, 보조 정보는 <aside>를 고려합니다. 푸터는 사이트 전역 푸터와 글 푸터(메타·태그)를 구분합니다.

<a class="skip-link screen-reader-text" href="#content">본문으로 건너뛰기</a>
<header>... 사이트 헤더 ...</header>
<nav aria-label="주 내비게이션">...</nav>
<main id="content">
  <article>
    <h1>단일 글 제목</h1>
    <section>
      <h2>섹션 제목</h2>
      <p>내용…</p>
    </section>
  </article>
</main>
<footer>... 사이트 푸터 ...</footer>

핵심 요약: 레이아웃은 landmark 태그로, 글/섹션은 article/section으로 구조화합니다.

3. 헤딩(H1/H2)·접근성(ARIA)·키보드 내비게이션

단일 글·페이지에는 보통 H1은 한 번만 사용하고, 본문 소제목은 모두 H2로 맞춥니다(본 시리즈 규칙). 목록 페이지(아카이브)에서는 항목 제목이 H2이고 페이지 최상단 제목이 H1이 되는 패턴이 일반적입니다.

ARIA는 시맨틱으로 표현이 어려울 때 보완합니다. 이미 의미가 분명한 태그(<nav>, <main>)에 불필요한 role을 중복 지정하지 않는 것이 좋습니다. 대신 aria-label로 목적을 명확히 해줍니다.

키보드 사용자를 위해 skip-link를 제공하고, 포커스가 보이도록 전역 CSS를 갖춥니다. 폼·버튼은 진짜 요소를 쓰며, <div>로 만든 가짜 버튼은 피합니다.

• 헤딩 규칙: H1 한 번, 섹션은 H2만 사용
• 랜드마크: main/nav/header/footer/aside로 구획
• 키보드:
  • skip-link 제공
  • 포커스 링 시인성 확보

핵심 요약: 헤딩 계층과 키보드 접근성은 SEO와 사용자 경험을 동시에 개선합니다.

4. 블록 에디터(Gutenberg) 마크업 이해

블록 에디터는 각 블록에 wp-block-* 클래스를 부여합니다. 예: 단락은 .wp-block-paragraph, 이미지 블록은 .wp-block-image입니다. 레이아웃 계열(그룹·열·커버)은 구조를, 콘텐츠 블록(문단·이미지·갤러리)은 의미를 표현합니다.

정렬 옵션은 alignwide, alignfull 등의 클래스로 표시되며, 테마는 이에 맞춰 컨테이너 폭을 제어해야 합니다. 불필요한 중첩 <div>는 피하고, 블록 패턴을 활용해 일관된 마크업을 유지합니다.

아래는 그룹 블록 안에 이미지·문단이 배치된 예시입니다. <figure>와 <figcaption>은 시맨틱·접근성 측면에서 권장됩니다.

<div class="wp-block-group alignwide">
  <figure class="wp-block-image">
    <img src="/images/sample.jpg" alt="예시 이미지" loading="lazy" />
    <figcaption>이미지 캡션</figcaption>
  </figure>
  <p class="wp-block-paragraph">블록 에디터 문단 예시입니다.</p>
</div>

핵심 요약: 블록 클래스와 정렬 규칙을 이해하면, 테마가 에디터 출력과 정확히 일치합니다.

5. Loop 마크업 패턴: 목록·단일·페이지

Loop는 글을 순회하며 <article>을 반복 출력합니다. 목록에서 제목은 보통 H2, 단일 글에서 제목은 H1입니다. 메타 정보는 <time datetime="">과 카테고리/태그 링크로 구성합니다.

아래 예시는 목록(아카이브) 템플릿의 전형적 구조입니다. 카드/리스트 중 어떤 형태든 article+헤딩+요약의 3요소를 유지하면 접근성과 SEO 모두 안정적입니다.

<section aria-label="글 목록">
  <article class="post">
    <h2 class="post-title"><a href="/post/sample">제목</a></h2>
    <p class="post-meta"><time datetime="2025-08-01">2025.08.01</time> · 카테고리</p>
    <div class="entry-summary">요약 텍스트…</div>
  </article>
  <!-- 반복 -->
</section>

핵심 요약: article·헤딩·요약의 기본형을 지키면 어떤 디자인에도 안전하게 확장됩니다.

6. 이미지·미디어 최적화: srcset·sizes·lazy

워드프레스는 기본적으로 반응형 이미지(srcset)를 출력해 해상도/화면 크기에 맞게 적절한 리소스를 선택합니다. 테마에서도 캡션이 필요한 이미지는 <figure> 구조를 사용하세요.

alt 텍스트는 이미지 목적을 설명하는 한 문장으로 작성하고, 장식 목적이면 빈 alt=""를 사용합니다. loading="lazy"는 초반 로딩량을 줄여 성능을 개선합니다.

히어로 이미지나 아트 디렉션이 필요한 경우 <picture>를 사용해 소스별 미디어쿼리를 적용할 수 있습니다.

<figure class="wp-block-image">
  <img 
    src="/images/cover-1200.jpg" 
    srcset="/images/cover-600.jpg 600w, /images/cover-1200.jpg 1200w" 
    sizes="(max-width: 700px) 100vw, 700px"
    alt="워드프레스 테마 커버 이미지" 
    loading="lazy" />
  <figcaption>테마 커버 이미지 캡션</figcaption>
</figure>

핵심 요약: 올바른 alt·srcset·lazy 조합은 성능·접근성·SEO를 동시에 향상합니다.

7. 폼·댓글 마크업: 레이블·자동완성·검증

폼 요소는 반드시 <label for>를 연결하고, 입력 목적에 맞는 type을 사용합니다(email, url, tel 등). 자동완성 속성(autocomplete)을 설정하면 UX가 좋아집니다.

검증은 브라우저 내장 속성(required, pattern, minlength)을 우선 활용하고, 커스텀 검증은 JS로 보강합니다. 에러 메시지는 시각적으로만이 아니라 스크린 리더에도 전달돼야 합니다.

댓글 폼에는 이름·이메일·URL의 필드를 올바른 type과 레이블로 출력하고, 제출 버튼은 실제 <button type="submit">을 사용합니다.

<label for="email">이메일</label>
<input id="email" name="email" type="email" autocomplete="email" required />

핵심 요약: 레이블 연결·적절한 type·자동완성·명확한 오류 피드백이 기본입니다.

8. 구조화 데이터·브레드크럼으로 맥락 강화

문서 의미를 검색엔진에 더 명확히 전달하려면 구조화 데이터(JSON-LD)를 고려합니다. 블로그 글에는 Article, 사이트 탐색에는 BreadcrumbList가 유용합니다.

브레드크럼은 <nav aria-label="breadcrumb">으로 마크업하고, 링크 텍스트는 현재 위치를 명확히 드러내야 합니다. JSON-LD는 <script type="application/ld+json">로 별도 삽입합니다.

아래 예시는 최소 구성의 BreadcrumbList입니다.

<script type="application/ld+json">{
  "@context":"https://schema.org",
  "@type":"BreadcrumbList",
  "itemListElement":[
    {"@type":"ListItem","position":1,"name":"Home","item":"https://example.com/"},
    {"@type":"ListItem","position":2,"name":"Blog","item":"https://example.com/blog/"},
    {"@type":"ListItem","position":3,"name":"HTML 필수 가이드","item":"https://example.com/wordpress-html-guide"}
  ]
}</script>

핵심 요약: JSON-LD와 브레드크럼은 검색결과 맥락 노출에 도움을 줍니다.

9. 다음 단계: CSS·JS 글로 이어 읽기

HTML로 의미를 정확히 표현했다면, 스타일은 CSS로 워드프레스 꾸미기에서 반응형·전역 토큰·그리드를, 인터랙션은 JavaScript 기본 & ES6에서 이벤트/모듈/비동기를 학습하세요.

블록 에디터 확장은 React로 Gutenberg 블록 개발하기에서 UI·속성·block.json을 연결해 보시면 흐름이 완성됩니다. 서버 연동은 워드프레스 REST API & JSON으로 이어집니다.

이 글의 예시 마크업은 PHP와 워드프레스 글의 템플릿/후크 개념과 함께 사용할 때 효과가 극대화됩니다.

핵심 요약: “HTML 의미 → CSS 스타일 → JS 인터랙션” 3단 흐름이 베스트 프랙티스입니다.

10. FAQ

Q. 단일 글에서 H2만 쓰면 SEO에 불리하지 않나요?
아니요. H1은 문서 제목, H2는 섹션 제목으로 충분합니다. 핵심은 일관된 계층과 의미론적 마크업입니다.

Q. 블록 에디터가 내보내는 많은 <div>를 줄일 수 있나요?
블록 구조상 필요한 래퍼는 유지됩니다. 패턴/템플릿으로 일관성을 확보하고, CSS로 과도한 중첩의 시각적 문제를 해결하세요.

Q. 이미지 alt는 어떻게 쓰나요?
이미지의 의도를 한 문장으로. 장식용이면 빈 alt=""로 스크린 리더가 건너뛰게 합니다. 캡션이 있다고 alt를 생략하진 않습니다.

Q. 브레드크럼은 꼭 필요할까요?
카테고리/태그 구조가 깊거나 대형 사이트라면 추천합니다. 사용자 위치 파악과 리치 결과 노출에 도움이 됩니다.

핵심 요약: 질문의 대부분은 “의미 우선” 원칙과 일관된 규칙으로 해결됩니다.

11. 출처

• WordPress Developer Handbook – Themes
• Block Editor Handbook
• MDN Web Docs – HTML
• W3C – WCAG 2.1
• Schema.org

👉 다음 단계 학습 가이드

• 디자인 확장: 마크업을 꾸미려면 ｢CSS로 워드프레스 꾸미기: 반응형·디자인 커스터마이징｣을 참고하세요.
• 동적 기능: 정적 HTML에서 벗어나려면 ｢JavaScript 기본 & ES6: 워드프레스 블록 에디터와 인터랙션의 출발점｣으로 이어가세요.