feat(blog): 글 읽기 레이아웃 개선 (#124)

Author: dev-wooyeon

blog/ui/components/TableOfContents.test.tsx

@@ -4,9 +4,12 @@ import { TableOfContents } from './TableOfContents';
 
 describe('TableOfContents', () => {
   it('renders native hash links and observes headings', () => {
-    const item = { id: 'section-1', text: '첫번째 섹션', level: 2 };
+    const items = [
+      { id: 'section-1', text: '첫번째 섹션', level: 2 },
+      { id: 'section-2', text: '두번째 섹션', level: 2 },
+    ];
     const header = document.createElement('h2');
-    header.id = item.id;
+    header.id = items[0].id;
     document.body.appendChild(header);
 
     const observeSpy = vi.fn();
@@ -24,22 +27,17 @@ describe('TableOfContents', () => {
     window.IntersectionObserver =
       MockIntersectionObserver as unknown as typeof window.IntersectionObserver;
 
-    const { container, getByRole } = render(<TableOfContents items={[item]} />);
+    const { container, getByRole } = render(<TableOfContents items={items} />);
 
     const link = getByRole('link', { name: '첫번째 섹션' });
     fireEvent.click(link);
 
-    expect(container.querySelector('nav')).toBeNull();
-    expect(document.body.querySelector('nav')).toHaveClass('bottom-8');
-    expect(document.body.querySelector('nav > div')).toHaveClass(
-      'h-full',
-      'overflow-y-auto'
+    expect(container.querySelector('nav')).toHaveClass('ark-article-toc');
+    expect(container.querySelector('nav > ol')).toHaveClass(
+      'ark-article-toc-list'
     );
-    expect(document.body.querySelector('ul')).toHaveClass('m-0', 'p-0');
-    expect(link).toHaveAttribute('href', `#${item.id}`);
-    expect(link).toHaveStyle({
-      fontFamily: 'var(--font-sans-emoji)',
-    });
+    expect(link).toHaveAttribute('href', `#${items[0].id}`);
+    expect(link).toHaveClass('ark-article-toc-link');
     expect(observeSpy).toHaveBeenCalledWith(header);
   });
 });

blog/ui/components/TableOfContents/TableOfContents.tsx

@@ -1,8 +1,6 @@
 'use client';
 
 import { useEffect, useState } from 'react';
-import { createPortal } from 'react-dom';
-import { clsx } from 'clsx';
 
 interface TocItem {
   id: string;
@@ -16,11 +14,6 @@ interface TableOfContentsProps {
 
 export default function TableOfContents({ items }: TableOfContentsProps) {
   const [activeId, setActiveId] = useState<string>('');
-  const [portalRoot, setPortalRoot] = useState<HTMLElement | null>(null);
-
-  useEffect(() => {
-    setPortalRoot(document.body);
-  }, []);
 
   useEffect(() => {
     if (items.length === 0) {
@@ -48,41 +41,35 @@ export default function TableOfContents({ items }: TableOfContentsProps) {
     return () => observer.disconnect();
   }, [items]);
 
-  if (items.length === 0 || !portalRoot) return null;
+  if (items.length < 2) return null;
 
-  return createPortal(
-    <nav
-      className="fixed right-8 top-20 bottom-8 hidden w-64 xl:block"
-      aria-label="이 글의 목차"
-    >
-      <div className="h-full overflow-y-auto rounded-[var(--radius-md)] bg-[var(--color-grey-50)] p-4">
-        <h2 className="text-sm font-semibold text-[var(--color-grey-900)] mb-4 sticky top-0 bg-[var(--color-grey-50)] pb-2">
-          이 글의 목차
-        </h2>
-        <ul className="m-0 flex list-none flex-col gap-1 p-0">
-          {items.map((item) => (
-            <li key={item.id}>
-              <a
-                href={`#${item.id}`}
-                aria-current={activeId === item.id ? 'location' : undefined}
-                className={clsx(
-                  'block w-full text-left text-sm py-1.5 px-3 rounded-[6px]',
-                  'transition-colors duration-[var(--duration-150)]',
-                  item.level > 2 && 'pl-6',
-                  activeId === item.id
-                    ? 'bg-[var(--color-accent)]/10 text-[var(--color-accent)] font-medium'
-                    : 'text-[var(--color-grey-600)] hover:text-[var(--color-grey-900)] hover:bg-[var(--color-grey-100)]'
-                )}
-                style={{ fontFamily: 'var(--font-sans-emoji)' }}
-              >
-                {item.text}
-              </a>
-            </li>
-          ))}
-        </ul>
-      </div>
-    </nav>,
-    portalRoot
+  return (
+    <nav className="ark-article-toc" aria-label="이 글의 목차">
+      <p className="ark-article-toc-title">목차</p>
+      <ol className="ark-article-toc-list">
+        {items.map((item, index) => (
+          <li key={item.id}>
+            <a
+              href={`#${item.id}`}
+              aria-current={activeId === item.id ? 'location' : undefined}
+              className={[
+                'ark-article-toc-link',
+                item.level === 3 && 'ark-article-toc-link-level-3',
+                item.level > 3 && 'ark-article-toc-link-level-4',
+                activeId === item.id && 'ark-article-toc-link-active',
+              ]
+                .filter(Boolean)
+                .join(' ')}
+            >
+              <span aria-hidden="true" className="ark-article-toc-number">
+                {String(index + 1).padStart(2, '0')}
+              </span>
+              <span>{item.text}</span>
+            </a>
+          </li>
+        ))}
+      </ol>
+    </nav>
   );
 }
 

blog/ui/pages/BlogPostPage.tsx

@@ -1,9 +1,6 @@
 import { Metadata } from 'next';
 import { notFound } from 'next/navigation';
-import {
-  getFeedData,
-  getAllFeedSlugs,
-} from '@/blog/services/post-repository';
+import { getFeedData, getAllFeedSlugs } from '@/blog/services/post-repository';
 import {
   getMdxSource,
   parseHeadingsFromMdx,
@@ -149,7 +146,7 @@ export default async function BlogPostPage({
       <ScrollDepthTracker slug={post.slug} />
 
       <article className="ark-article">
-        <Container size="md">
+        <Container size="md" className="ark-article-container">
           {/* Header */}
           <header className="ark-article-header">
             <span className="mb-4 inline-block rounded-[var(--radius-selection)] bg-[var(--color-bg-secondary)] px-3 py-1 text-xs font-medium text-[var(--color-text-secondary)]">
@@ -167,6 +164,8 @@ export default async function BlogPostPage({
             </div>
           </header>
 
+          <TableOfContents items={tocItems} />
+
           {/* Content */}
           <div className="prose">
             <Content components={mdxComponents} />
@@ -176,7 +175,7 @@ export default async function BlogPostPage({
 
       {/* Comments */}
       <section className="py-12">
-        <Container size="md">
+        <Container size="md" className="ark-article-container">
           <GiscusComments slug={slug} />
         </Container>
       </section>
@@ -206,8 +205,6 @@ export default async function BlogPostPage({
           isAccessibleForFree: true,
         }}
       />
-
-      <TableOfContents items={tocItems} />
     </>
   );
 }

docs/README.md

@@ -1,6 +1,6 @@
 # 문서 인덱스
 
-Last updated: 2026-07-24
+Last updated: 2026-07-28
 
 이 인덱스는 현재 코드베이스와 함께 유지해야 하는 문서만 추적한다. 계속
 업데이트할 문서가 아니라면 삭제하거나, 오래 남겨야 하는 결정만 ADR로 옮긴다.
@@ -50,6 +50,7 @@ Last updated: 2026-07-24
 - `docs/adr/0049-share-publication-policy-data-with-audit.md`
 - `docs/adr/0050-retire-series-navigation-and-enforce-listed-post-policy.md`
 - `docs/adr/0052-use-repo-local-public-writing-review-workflow.md`
+- `docs/adr/0053-use-inline-table-of-contents-for-article-reading.md`
 - `docs/blog-quality-guide.md`
 - `docs/content-publication-candidates.md`
 - `docs/database/db-schema.md`

docs/adr/0053-use-inline-table-of-contents-for-article-reading.md

@@ -0,0 +1,51 @@
+# 0053. 글 읽기 흐름에 인라인 목차를 사용한다
+
+Date: 2026-07-28
+Status: Accepted
+
+## 배경
+
+기존 글 상세 화면은 본문 바깥의 Portal 목차를 사용했다. 이 방식은 목차를
+항상 화면에 노출할 수 있지만, 본문과 목차의 관계가 분리되어 글의 실제
+읽기 흐름과 반응형 레이아웃을 함께 이해하기 어렵다. 본문 안에 목차를
+배치하면 짧은 글에서 목차를 숨길 수 있고, 독자가 글을 시작하는 위치에서
+구조를 바로 확인할 수 있다.
+
+## 결정
+
+- 목차는 글 본문 컨테이너 안에 인라인으로 렌더링한다.
+- 목차 항목이 2개 미만이면 렌더링하지 않는다.
+- 목차는 번호, 계층 들여쓰기, 현재 활성 heading 상태를 제공한다.
+- 데스크톱 콘텐츠 레이아웃에서는 본문과 댓글에 같은
+  `ark-article-container` 정렬 정책을 적용한다.
+- 기존 viewport별 rail과 타이포그래피 규칙은 ADR 0051을 유지하고, 이 ADR은
+  글 내부 탐색 방식에 대한 결정을 추가한다.
+
+## 결과
+
+- 목차가 본문 시작과 가까워져 글의 구조를 빠르게 파악할 수 있다.
+- 짧은 글에는 불필요한 목차가 나타나지 않는다.
+- 본문과 댓글이 같은 콘텐츠 열에 정렬되어 넓은 데스크톱 화면에서도
+  읽기 흐름과 대화 영역의 시작점이 일치한다.
+- 목차가 본문 흐름에 포함되므로 Portal 기반의 고정 목차보다 화면에
+  항상 노출된다는 보장은 줄어든다.
+
+## 검토한 대안
+
+- **기존 Portal 목차 유지**: 항상 접근할 수 있지만 본문과 구조적으로
+  분리되고 짧은 글에도 별도 탐색 UI가 남는다.
+- **데스크톱에서만 Portal 목차 유지**: 데스크톱과 모바일의 탐색 모델이
+  달라지고, 본문과 목차의 위치 관계를 일관되게 설명하기 어렵다.
+- **본문과 댓글의 서로 다른 정렬 유지**: 넓은 화면에서 댓글이 본문보다
+  오른쪽으로 밀려 콘텐츠 열의 시각적 기준선이 어긋난다.
+
+## 검증
+
+- 목차 컴포넌트의 2개 미만 항목, 계층, 활성 상태 테스트
+- viewport stylesheet selector 및 정렬 정책 단위 테스트
+- 전체 lint, CSS syntax 검사, production build
+
+## Related History
+
+- `7f3f6ec`: 본문 Portal 목차를 인라인 목차로 변경한 초기 구현
+- `a79f661`: 커밋 메시지 및 PR 메타데이터 정리

docs/adr/README.md

@@ -70,6 +70,7 @@ ADR은 AI 협업 가이드와 별개의 문서다. 사람이 결정했든 AI가
 | [0050](0050-retire-series-navigation-and-enforce-listed-post-policy.md)            | Accepted   | 시리즈 탐색을 제거하고 발행 정책을 repository에서 강제한다   |
 | [0051](0051-use-viewport-specific-reading-layout-and-type-scale.md)                 | Accepted   | viewport별 읽기 레이아웃과 타이포그래피 스케일을 사용한다     |
 | [0052](0052-use-repo-local-public-writing-review-workflow.md)                       | Accepted   | 공개 글 검토에 repo-local writing review workflow를 사용한다   |
+| [0053](0053-use-inline-table-of-contents-for-article-reading.md)                   | Accepted   | 글 읽기 흐름에 인라인 목차를 사용한다                         |
 
 ## 작성 조건
 

styles/globals.css

@@ -184,11 +184,77 @@
 
 .ark-site-external-link {
   color: var(--color-text-primary);
-  font-size: var(--text-base);
+  font-size: var(--text-sm);
   font-weight: var(--font-normal);
   line-height: 1.5rem;
 }
 
+.ark-article-toc {
+  margin: var(--space-12) 0;
+  padding: var(--space-6) 0;
+  border-top: 1px solid var(--color-divider);
+  border-bottom: 1px solid var(--color-divider);
+}
+
+.ark-article-toc-title {
+  margin: 0 0 var(--space-4);
+  color: var(--color-grey-500);
+  font-family: var(--font-mono);
+  font-size: var(--text-xs);
+  font-weight: var(--font-medium);
+  letter-spacing: var(--tracking-wide);
+}
+
+.ark-article-toc-list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-1);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.ark-article-toc-link {
+  display: flex;
+  gap: var(--space-3);
+  padding: var(--space-1) 0;
+  color: var(--color-grey-600);
+  font-family: var(--font-sans-emoji);
+  font-size: var(--text-sm);
+  line-height: 1.5rem;
+  transition: color var(--duration-150) var(--ease-default);
+}
+
+.ark-article-toc-link:hover {
+  color: var(--color-grey-900);
+}
+
+.ark-article-toc-link:focus-visible {
+  outline: 2px solid var(--color-accent);
+  outline-offset: 0.25rem;
+}
+
+.ark-article-toc-link-level-3 {
+  padding-left: var(--space-4);
+}
+
+.ark-article-toc-link-level-4 {
+  padding-left: var(--space-8);
+}
+
+.ark-article-toc-link-active {
+  color: var(--color-accent);
+  font-weight: var(--font-medium);
+}
+
+.ark-article-toc-number {
+  flex-shrink: 0;
+  color: var(--color-grey-400);
+  font-family: var(--font-mono);
+  font-size: var(--text-xs);
+  line-height: 1.5rem;
+}
+
 /* ===== Article Entry ===== */
 
 .ark-article {
@@ -636,12 +702,17 @@
 .prose code {
   font-family: var(--font-mono);
   font-size: 0.875em;
-  background-color: var(--color-bg-secondary);
-  color: var(--color-text-primary);
-  padding: 0.125rem 0.375rem;
+  background-color: var(--color-code-inline-bg);
+  color: var(--color-code-inline-fg);
+  padding: 0.1rem 0.35rem;
   border-radius: var(--radius-action);
 }
 
+.prose :not(pre) > code {
+  background-color: var(--color-code-inline-bg);
+  color: var(--color-code-inline-fg);
+}
+
 /* Inline code should not have background if it's inside pre */
 .prose pre code {
   background-color: transparent;

styles/globals.test.ts

@@ -84,6 +84,20 @@ describe('globals styles', () => {
     expect(globalsContent).toContain('max-width: 34rem;');
   });
 
+  it('keeps external links visually secondary to primary navigation', () => {
+    expect(globalsContent).toContain('.ark-site-external-link {');
+    expect(globalsContent).toContain('font-size: var(--text-sm);');
+  });
+
+  it('keeps inline code lighter than fenced code blocks', () => {
+    expect(tokensContent).toContain('--color-code-inline-bg: #d8d8dc;');
+    expect(tokensContent).toContain('--color-code-inline-fg: #52525b;');
+    expect(tokensContent).toContain('--color-code-bg: #3f3f46;');
+    expect(globalsContent).toContain(
+      '.prose :not(pre) > code {\n  background-color: var(--color-code-inline-bg);'
+    );
+  });
+
   it('gives the mobile home page a split first-entry layout', () => {
     expect(mobileViewportContent).toContain(
       ".ark-site-grid[data-page-layout='home']"
@@ -134,6 +148,12 @@ describe('globals styles', () => {
     expect(contentViewport).toContain(
       ".ark-site-grid[data-page-layout='content'] .ark-article {\n    padding-top: 0;"
     );
+    expect(contentViewport).toContain('position: sticky;');
+    expect(contentViewport).toContain('top: 2.5rem;');
+    expect(contentViewport).toContain(
+      ".ark-site-grid[data-page-layout='content'] .ark-article-container {"
+    );
+    expect(contentViewport).toContain('margin-left: 0;');
   });
 
   it('matches hero and primary navigation sizes at intermediate widths', () => {