프로젝트 구조

이 문서는 저장소 내 문서 사이트 구조를 한 번에 이해할 수 있도록 루트 구조와 하위 폴더 역할을 분리해 설명합니다. 전체 트리만 나열하면 실제 운영 시 어느 위치를 수정해야 하는지 판단이 어려우므로, 각 경로의 책임을 함께 정리했습니다. 아래 순서대로 보면 설정, 스타일, 플러그인, 콘텐츠 흐름을 빠르게 파악할 수 있습니다.

전체 구조 설명

전체 구조는 docs를 기준으로 설정 파일, 정적 자산, 스타일, 플러그인, 콘텐츠가 분리되어 있습니다. 운영 중에는 변경 목적에 맞는 영역만 수정하는 것이 안전하며, 특히 content와 plugins는 영향 범위가 다르므로 구분해서 관리해야 합니다.

• docs/
  • astro.config.mjs
  • public/
    • directives.js
    • scroll-to-top.js
  • src/
    • assets/
      • migration-checks.css
      • w0-migration/
        • prose.css
        • interactive.css
    • plugins/
      • remarkDirectiveComponents.js
      • remarkObsidianEmbed.js
      • rehypeImage.js
      • rehypeVideo.js
    • content/
      • docs/
        • sndim/
        • feature-guide/
        • markdown-guide/
        • guides/

루트 주요 항목 역할

• docs/astro.config.mjs: 사이트 메타, 통합 설정, 사이드바 자동 생성 규칙을 관리하는 진입점입니다.
• docs/public/: 클라이언트 런타임 스크립트와 정적 파일을 보관하며 빌드 결과에 그대로 포함됩니다.
• docs/src/assets/: 테마 스타일과 상호작용 스타일을 관리하는 영역으로, 렌더링 표현 변경 시 우선 확인합니다.
• docs/src/plugins/: 마크다운/디렉티브/미디어 파싱 동작을 확장하는 로직이 위치합니다.
• docs/src/content/docs/: 실제 문서 본문이 위치하며 섹션-문서 단위로 운영합니다.

하위 폴더들의 역할 구조 설명

하위 폴더는 기능 책임에 맞춰 분리되어 있으며, 작성자는 문서 유형에 따라 섹션을 선택해 작성합니다. 섹션 단위가 명확하면 사이드바 탐색성과 리뷰 기준이 함께 안정화됩니다.

• docs/
  • src/
    • content/
      • docs/
        • sndim/
          • quick-start/
            • index.md
          • content-workflow/
            • index.md
        • markdown-guide/
          • 01-elements/
            • index.md
          • 02-image/
            • index.md
          • 03-video/
            • index.md
          • 04-layout-footnotes/
            • index.md
        • feature-guide/
          • interactive-inline/
            • index.md
          • interactive-image/
            • index.md
          • interactive-video/
            • index.md
          • interactive-filetree/
            • index.md
          • interactive-callouts-faq/
            • index.md
        • guides/
          • project-structure/
            • index.md
          • css-maintenance/
            • index.md

섹션별 역할

• sndim: 프로젝트 소개, 시작 흐름, 운영 정책처럼 상위 운영 가이드를 다룹니다.
• markdown-guide: 일반 마크다운 문법과 미디어 작성 규칙을 다룹니다.
• feature-guide: 디렉티브와 상호작용 기능 사용법을 다룹니다.
• guides: 유지보수/구조/운영 보조 문서를 다룹니다.

문서 작성 단위 구조 설명

모든 문서는 section/slug/index.md를 기준으로 생성하며, 미디어도 같은 폴더에 둡니다. 이 규칙을 지키면 경로 참조가 단순해지고 문서 이동 또는 리네임 시 수정 범위를 최소화할 수 있습니다.

• docs/
  • src/
    • content/
      • docs/
        • {section}/
          • {slug}/
            • index.md
            • image.png
            • test-video.mp4

작성 단위 운영 설명

• index.md는 문서 본문과 frontmatter를 포함하는 기준 파일입니다.
• image.png, test-video.mp4 같은 미디어는 같은 폴더에 보관해 상대 경로 참조를 고정합니다.
• 문서 제목은 frontmatter title을 사용하며 사이드바 표기에도 동일하게 반영됩니다.

운영 규칙

• 문서 단위는 section/slug/index.md
• 미디어는 문서와 같은 폴더에 보관
• 사이드바 라벨은 문서 title 기준으로 자동 반영