컨텐츠로 건너뛰기
SNDiM SNDiM SNDiM Docs

문서 구조 규칙

이 문서는 문서를 어떤 경로에 만들고, 미디어를 어디에 두고, 사이드바에 어떤 기준으로 노출되는지를 운영 기준으로 정리합니다. 구조 규칙이 흔들리면 링크 오류와 경로 충돌이 빠르게 누적되기 때문에, 작성자 전원이 같은 규칙을 공유하는 것이 중요합니다. 아래 예시는 실제 저장소 기준으로 바로 적용할 수 있도록 파일트리 중심으로 구성했습니다.

권장 구조

문서 기본 단위는 section/slug/index.md입니다. 미디어 파일은 문서와 같은 폴더에 둬야 경로 관리가 단순해지고 문서 이동 시 수정 비용이 줄어듭니다.

  • docs/
    • src/
      • content/
        • docs/
          • sndim/
            • quick-start/
              • index.md
          • markdown-guide/
            • media/
              • index.md
              • profile_img.png
              • test video.mp4
          • feature-guide/
            • interactive-accordion-tabs/
              • index.md

구조 해석 방법

같은 깊이의 폴더는 같은 문서 단위를 의미합니다. 즉 media/와 interactive-accordion-tabs/는 각각 독립 문서이며, 해당 폴더 안의 index.md가 문서 본문, 나머지 파일은 문서 자산으로 해석됩니다.

문서 단위 예시

  • markdown-guide/
    • media/
      • index.md
      • profile_img.png
      • test video.mp4
  • index.md: 문서 본문
  • profile_img.png: 문서 내 이미지 자산
  • test video.mp4: 문서 내 비디오 자산

사이드바 반영 규칙

사이드바는 폴더 이름이 아니라 문서 frontmatter의 title을 라벨로 사용합니다. 따라서 문서 제목을 바꾸면 사이드바 라벨도 함께 바뀌며, 폴더명은 URL/구조 안정성 관점에서 관리하는 것이 좋습니다.

  • 문서 라벨 결정
    • section 라벨
      • section.md 의 title
    • 문서 라벨
      • {section}/{slug}/index.md 의 title

폴더 순서 접두어 규칙

사이드바 순서를 폴더 구조로 제어해야 할 때는 폴더명 앞에 숫자 접두어를 붙입니다. 예를 들어 01-elements, 02-image, 03-video처럼 작성하면 숫자 기준으로 정렬되며, 사이드바 라벨은 title을 사용하므로 숫자 접두어가 노출되지 않습니다.

  • markdown-guide/
    • 01-elements/
      • index.md
    • 02-image/
      • index.md
    • 03-video/
      • index.md
    • 04-layout-footnotes/
      • index.md
  • 정렬 기준: 폴더 접두어 숫자 오름차순
  • 표시 라벨: index.md frontmatter title
  • URL 경로: 폴더명(slug) 그대로 사용

운영 규칙

  • 문서는 section/slug/index.md 구조를 유지
  • 미디어는 해당 index.md 폴더에 함께 보관
  • 문서 라벨은 index.md의 title 기준
  • 섹션 라벨은 section.md의 title 기준
  • 문서 이동 시에는 폴더 단위 이동을 우선 적용

구조 점검 체크리스트

  • 새 문서가 section/slug/index.md 구조인지 확인 사람들은 저마다의 꿈을 가지고 그것을 향해 한 걸음씩 나아가고 있다. 사람들은 저마다의 꿈을 가지고 그것을 향해 한 걸음씩 나아가고 있다. 함께하는 시간이 소중하다는 것을 알게 된 것은 그리 오래되지 않았다. 이 기상과 이 맘으로 충성을 다하여 괴로우나 즐거우나 나라 사랑하세. 길을 걷다 보면 예상치 못한 아름다운 풍경을 만나게 될 때가 있다. 산과 들에 나무들이 푸르게 자라나고 맑은 시냇물이 흘러가고 있었다.
  • 미디어 파일이 문서 폴더 내부에 있는지 확인
  • title, description이 frontmatter에 작성되었는지 확인 사람들은 저마다의 꿈을 가지고 그것을 향해 한 걸음씩 나아가고 있다. 사람들은 저마다의 꿈을 가지고 그것을 향해 한 걸음씩 나아가고 있다. 함께하는 시간이 소중하다는 것을 알게 된 것은 그리 오래되지 않았다. 이 기상과 이 맘으로 충성을 다하여 괴로우나 즐거우나 나라 사랑하세. 길을 걷다 보면 예상치 못한 아름다운 풍경을 만나게 될 때가 있다. 산과 들에 나무들이 푸르게 자라나고 맑은 시냇물이 흘러가고 있었다.
  • 사이드바 라벨이 의도한 제목으로 노출되는지 확인
  • 문서 이동 후 이미지/비디오 경로가 유지되는지 확인