북(Book) 시스템 활용

북(Book) 시스템은 개별 마크다운 문서들을 순서에 맞게 엮어 **연속적인 도서/가이드(Course)**로 제공하는 몰입형 리더(Reader) 기능입니다. 전체 읽기 진도 트래킹과 통합 PDF 출판 기능을 지원합니다.

모든 북 설정은 콘텐츠 저장소 최상단의 @books/ 폴더 내에 YAML 형식으로 작성합니다.

파일 위치: @books/도서아이디.yml
필수 스키마 주석: 파일 최상단에 검증 및 자동완성을 위한 주석을 포함해야 합니다.

# yaml-language-server: $schema=http://localhost:3000/schemas/book.json

id: "doc-author-guide"
title: "문서 작성자 통합 가이드"
description: "Git Static Doc Server에서 문서를 작성하는 방법"
cover_image: ""                       # 비워둘 시 자동 그라데이션 커버 생성
author: "플랫폼 인프라팀"

chapters:
  - title: "1장. 챕터 제목"
    description: "챕터 소개"
    posts:
      - "docs-guide/docs-book/1-basic-guide"  # .md 확장자 생략

[!TIP] IDE(VS Code 등)에서 위 스키마 주석을 넣으면 Ctrl + Space를 통해 속성 자동완성과 툴팁 안내를 받을 수 있어 작성 오류를 예방할 수 있습니다.

2. Book 전용 문서 (`book_only`

북의 단원으로는 포함되지만, 일반 카테고리 목록(블로그 피드)이나 검색 결과에는 독립적으로 노출되지 않도록 하려면 마크다운 문서의 Frontmatter에 book_only: true를 선언합니다.

---
book_only: true
---

독자의 상황(운영체제, 사용하는 도구 등)에 따라 다르게 읽어야 하는 문서가 있다면 선택형 단원으로 묶어 제공할 수 있습니다.

chapters:
  - title: "2장. 환경별 도구 설정"
    description: "선호하는 툴을 선택하세요."
    posts:
      - title: "에디터 선택"
        description: "사용 중인 에디터에 맞는 가이드를 선택해 주세요."
        options:
          - slug: "docs-guide/docs-book/vscode-guide"
            label: "VS Code 가이드"
          - slug: "docs-guide/docs-book/intellij-guide"
            label: "IntelliJ 가이드"

[!IMPORTANT]

options 목록이 존재하면 시스템이 자동으로 **선택형 단원(type: "choice")**으로 감지합니다.

독자가 카드를 클릭하면 선택 상태가 저장되며, 이전/다음 내비게이션 진행 시 선택하지 않은 대안 문서는 자동으로 건너뜁니다.

PDF 다운로드 시에는 독자가 놓치는 내용이 없도록 모든 분기 경로의 문서가 포함됩니다.

2. Book 전용 문서 (book_only

2. Book 전용 문서 (`book_only`