문서 작성 워크플로우

이 문서는 실제 문서 작성자가 어떤 순서로 문서를 만들고 검증해야 하는지를 운영 기준으로 정리한 워크플로우입니다. 작성 단계와 검증 단계를 분리해 설명해, 초안 작성과 배포 전 확인을 혼동하지 않도록 구성했습니다. 각 단계는 바로 실행할 수 있도록 경로 예시, 명령어, 확인 포인트를 함께 제공합니다.

작성 단계

문서 작성은 먼저 위치를 정확히 만든 뒤 메타데이터를 채우고 본문을 작성하는 흐름이 가장 안정적입니다. 특히 section/slug/index.md 구조를 먼저 고정하면 이후 미디어 경로, 사이드바 반영, 링크 관리가 모두 단순해집니다.

문서 위치 만들기

아래처럼 docs/src/content/docs/{section}/{slug}/index.md 구조를 먼저 생성합니다. 예시에서는 markdown-guide 섹션에 my-first-doc 문서를 추가하는 경우를 보여줍니다.

• docs/
  • src/
    • content/
      • docs/
        • markdown-guide/
          • my-first-doc/
            • index.md

메타데이터 작성

문서 파일 생성 직후 frontmatter를 먼저 작성합니다. title, description을 초기에 고정하면 문서 제목, 사이드바 라벨, 검색 요약이 동시에 정리됩니다.

---
title: 내 첫 문서
description: 문서 목적을 한두 문장으로 설명합니다.
---

본문 및 미디어 작성

본문은 문서 목적 문장을 먼저 쓰고 필요한 디렉티브를 추가하는 순서로 작성합니다. 이미지/비디오 파일은 반드시 같은 폴더에 배치해 경로 충돌을 줄입니다.

• docs/
  • src/
    • content/
      • docs/
        • markdown-guide/
          • my-first-doc/
            • index.md
            • image.png
            • demo.mp4

검증 단계

검증은 렌더링 확인과 빌드 확인을 분리해서 진행하는 것이 좋습니다. 각 단계에서 확인 포인트를 명확히 두면 리뷰 기준을 팀 단위로 재사용하기 쉬워집니다.

검증 명령어

아래 명령어를 실행해 개발 화면 확인과 정적 빌드 검증을 순서대로 진행합니다.

pnpm run dev
pnpm run build

검증 항목

• pnpm run dev: 로컬 렌더링, 레이아웃, 이미지/비디오 표시, 디렉티브 동작 확인
• pnpm run build: 정적 빌드 성공 여부와 링크/페이지 생성 상태 확인
• 공통 확인: 내부 링크 연결, 사이드바 노출, 문서 제목/설명 반영 여부 확인

참고 문서

아래 문서들은 실제 작성 시 함께 열어두면 가장 효율적인 기준 문서입니다. 문서별 역할이 다르므로, 현재 작성 중인 내용 유형에 맞춰 참조 문서를 선택해 사용하는 것이 좋습니다.

• 마크다운 기본 요소 : 기본 마크다운 문법, 제목/목록/표/코드/각주 등 문서 뼈대 작성 규칙을 포함합니다.
• 이미지 : 오리지널 마크다운 이미지 문법과 경로 표기 규칙을 포함합니다.
• 비디오 : 오리지널 마크다운 기준의 비디오 링크 작성 규칙을 포함합니다.
• 아코디언과 탭 : 아코디언, 탭, FAQ 등 접기/전환형 디렉티브의 실사용 패턴을 포함합니다.