Summary Card와 Section TOC 전체 가이드

Summary Card와 Section TOC는 링크가 가리키는 의미를 더 읽기 쉬운 블록으로 표현하는 링크 기반 Projection이다. 원문 링크를 전용 Markdown 문법으로 바꾸지 않고, 어떤 발생 위치를 어떻게 보여 줄지만 .glif profile에 저장한다.

두 Projection은 원문을 복사해 별도 데이터로 보관하지 않는다. Summary Card는 현재 문서 메타데이터를 다시 읽고, Section TOC는 현재 Scope의 문서 인덱스를 다시 읽는다. 제목이나 하위 문서가 바뀌면 다음 projection 계산에서 최신 source가 근거가 된다.

준비된 예제

• 실습 Binder 소개
• 두 Projection이 저장된 완성 예제
• Summary Card 선택 실습
• Section TOC 선택 실습
• Guides 컨테이너 인덱스

예제 폴더 전체를 내려받아 Glif에서 Scope로 연다. 완성 상태를 먼저 보려면 00_release-readiness.md를 열고, 선택 과정을 처음부터 반복하려면 01_summary-card.md와 02_section-toc.md를 사용한다.

공통 원문 계약

Projection으로 바꿀 링크는 한 줄을 단독으로 차지해야 한다.

[Current document summary](#)

[Guides](guides/_index.md)

다음 링크는 역할이 다르거나 계약을 만족하지 않는다.

Summary Card와 Section TOC는 drag/drop의 일반 reference view 목록에서 무조건 제안되지 않는다. source occurrence 자체가 위 조건을 만족하는지 확인할 수 있을 때 링크 미리보기에서만 선택지가 나타난다.

Summary Card 만들기

1. 작성된 메타데이터 준비

Summary Card가 읽을 수 있는 대표 frontmatter는 다음과 같다.

---
title: Release readiness summary
summary: Authored metadata becomes a compact card without copying it into the body.
tags: [guide, summary]
updated: 2026-08-01
---

카드는 다음 우선순위로 값을 고른다.

가이드 실증 중 editor body와 frontmatter가 분리된 런타임에서 authored summary가 누락되는 문제가 발견됐다. 현재 구현은 링크 위치 계산에는 editor body를 유지하고, 카드 모델을 만들 때만 같은 문서의 frontmatter를 다시 결합한다. 이 경계를 지켜야 profile locator와 Markdown 편집 위치가 흔들리지 않는다.

2. 현재 문서 링크 작성

본문에서 다음 링크를 독립된 줄에 둔다.

[Current document summary](#)

3. 링크 미리보기에서 선택

1. Current document summary 위에 pointer를 잠시 둔다.
2. 현재 문서 미리보기가 열리는지 확인한다.
3. 요약 카드를 선택한다.
4. pointer를 editor 밖으로 옮겨 결과만 확인한다.

4. 카드 결과 대조

다음 항목을 대조한다.

• eyebrow가 Document summary인지
• 제목이 frontmatter의 title인지
• 설명이 본문 첫 문단이 아니라 작성된 summary인지
• 태그와 수정일이 있을 때만 나타나는지
• Reveal source가 있는지

카드에서 문장을 직접 편집하지 않는다. 제목이나 요약을 바꾸려면 문서 메타데이터를 수정한다. Source가 바뀐 뒤 카드를 다시 계산하면 같은 occurrence가 최신 값을 읽는다.

Section TOC 만들기

1. 실제 컨테이너 인덱스 준비

대상 폴더에 실제 _index.md가 있어야 한다.

guides/
├── _index.md
├── 10_getting-started.md
├── 20_advanced-workflows.md
└── nested/
    └── 30_release-checks.md

guides/_index.md가 guides/의 owner다. 단지 guides/라는 폴더가 있거나 일반 문서가 비슷한 제목을 갖는 것만으로는 Section TOC를 만들지 않는다.

하위 문서의 title, summary와 weight는 목차 label, 보조 설명과 순서에 사용된다. 유한한 숫자 weight가 먼저 오고, 나머지는 정규화한 상대 경로 순서로 정렬한다.

2. 인덱스 링크 작성

[Guides](guides/_index.md)

3. 대상 미리보기에서 선택

1. Guides 링크 위에 pointer를 잠시 둔다.
2. 미리보기에 guides/_index.md와 인덱스 설명이 나타나는지 확인한다.
3. 섹션 목차를 선택한다.
4. 대상 제목과 하위 항목을 확인한다.

4. 범위와 순서 대조

기본 범위는 최대 깊이 2, 최대 100개 항목이다. profile 계약은 각각 최대 깊이 6, 최대 500개로 제한한다. 범위를 넘는 요청은 무한 탐색하지 않고 cap을 적용하며 diagnostic을 남긴다.

목차에는 다음 조건을 모두 만족하는 항목만 들어간다.

• owner 경로 아래의 Markdown 문서
• 숨김 상태가 아닌 문서
• 현재 인덱스에서 사용할 수 있고 게시 가능한 문서
• 설정한 깊이와 항목 수 안의 문서
• Hugo에서는 실제 publish manifest에 포함된 문서

절대 파일 경로, .glif 내부 파일, 이미지 같은 비 Markdown 파일과 다른 폴더의 문서는 항목으로 노출하지 않는다.

Reveal source와 원래 링크로 돌아가기

두 Projection의 Reveal source를 누르면 같은 Markdown occurrence를 선택하고 원문 링크를 보여 준다. 이는 projection 설정을 삭제하는 동작이 아니다. pointer나 selection이 해당 범위를 벗어나면 저장된 projection이 다시 나타난다.

계속 일반 링크로 사용하려면 링크 미리보기에서 링크를 선택한다. 이때 해당 occurrence의 reference profile entry를 제거하고 Markdown 링크는 그대로 둔다.

링크 label, href 또는 발생 순서가 바뀌면 Glif는 저장된 index만 믿지 않고 label과 href proof를 함께 대조한다. 안전하게 다시 찾을 수 없으면 stale 또는 ambiguous로 진단하고 원래 링크를 유지한다.

대상이 없거나 읽히지 않을 때

missing/_index.md가 없으면 빈 Section TOC나 성공한 것처럼 보이는 placeholder를 만들지 않는다. 링크는 원래 Markdown으로 남고 사용자는 href를 읽고 고칠 수 있다.

Desktop과 Hugo 결과

Desktop은 interactive projection을 보여 주고 Hugo publish는 지원되는 결과를 publish copy의 일반 Markdown으로 materialize한다.

이번 fixture를 실제 publish materialization 함수에 전달한 Summary 결과는 다음 의미를 가진다.

Document summary

Release readiness summary

Authored metadata becomes a compact card without copying it into the body.

guide · summary

Updated: 2026-08-01

Section TOC는 다음 publish 구조로 바뀐다.

Section TOC: Guides

• Getting started Open the Scope, inspect the source links, and apply the first projection.
• Advanced workflows Verify ordering, bounded descendants, publish materialization, and readable fallback.
  • Nested release checks A depth-two entry that proves the Section TOC boundary.

Hugo 결과는 Desktop DOM을 복사하지 않는다. source 의미를 일반 blockquote와 목록으로 바꾸므로 JavaScript가 없어도 읽을 수 있고, Desktop의 hover·selection 상태는 게시물에 섞이지 않는다.

키보드와 접근성 경계

• Summary Card root는 Document summary, Section TOC root는 Section TOC라는 accessible name을 가진다.
• 제목과 하위 항목은 화면 text와 접근성 트리 양쪽에서 읽을 수 있다.
• Reveal source는 실제 button이며 keyboard focus로 실행할 수 있다.
• 좁은 폭과 200% reflow 자동 검증에서 카드가 본문 밖으로 넘치지 않아야 한다.
• 원래 Markdown link fallback은 keyboard link navigation을 유지한다.

자동 브라우저 검증은 이름, focus 순서와 reflow를 확인한다. 사람의 실제 screen-reader 청취와 모든 assistive technology·browser 조합까지 완료했다고 주장하지 않는다. 최종 release qualification에서는 대표 screen reader로 두 카드의 이름, 항목 순서, Reveal source 결과를 직접 듣는다.

실증 영상

영상은 실제 Glif Desktop에서 두 독립 링크를 차례로 열어 요약 카드, 섹션 목차를 선택하고, Reveal source와 대상 없음 fallback을 확인한다. 파란 원과 아래 caption은 캡처 안내 overlay이며 Markdown이나 profile에 저장되지 않는다.

이번 실증 결과

Windows Glif 0.1.0 개발 release candidate의 1200×800 client area에서 확인했다.

• Summary Card 링크 미리보기 선택 성공
• 작성된 summary와 tags 반영 성공
• 실제 _index.md 기반 Section TOC 선택 성공
• Getting started → Advanced workflows → 깊이 2 Nested release checks 순서 확인
• Reveal source와 missing target 일반 링크 fallback 확인
• 실제 publish materialization 함수에서 Summary와 Section TOC 결과 생성 성공
• publish materialization diagnostic 0개
• 공개 fixture 전후 SHA-256 동일
• MP4·WebM 10.9초, 1200×800

기계 판독 실증 JSON에는 Desktop 관찰 결과, Hugo materialized excerpt, 원문 보존과 검증하지 않은 접근성 경계가 기록돼 있다. 사용자 절대 경로와 임시 profile 경로는 포함하지 않는다.

완료 기준

• VW-38: 독립된 # 링크를 Summary Card로 선택한다.
• VW-38: frontmatter의 작성된 summary를 body fallback보다 우선한다.
• VW-39: 실제 _index.md의 owner 범위에서 Section TOC를 만든다.
• VW-39: 깊이·항목 수·publish manifest 경계를 적용한다.
• 두 Projection에서 Reveal source로 같은 원문 occurrence에 돌아간다.
• missing·stale·ambiguous 상태에서 일반 링크를 보존한다.
• Desktop accessible name과 자동 reflow 검증 경계를 설명한다.
• Hugo publish가 정적 Markdown으로 materialize되는 결과를 대조한다.
• 이미지·영상·JSON에 사용자 절대 경로를 남기지 않는다.
• 최종 release candidate에서 대표 screen reader 청취 qualification을 수행한다.

마지막 미완료 항목은 기능 동작 실패가 아니라 공개 접근성 qualification의 잔여다. 완료 전까지 “모든 screen reader에서 검증됨”이라고 표현하지 않는다.