1) 현재 상태 요약

• VitePress 문서 사이트가 Cloudflare Pages에 배포되고 있음
• Docs Quality Check CI가 문서 빌드/markdown lint/link check를 수행
• markdownlint는 치명 규칙(fail) + 스타일 규칙(warning) 이중 운영
• PR 템플릿과 pre-commit 훅으로 문서 품질 게이트를 강화
• 현재 로컬 작업 폴더는 D:\CODE\AICODE\mVitePress
• main 브랜치는 origin/main과 동기화되어 있음
• 마지막 반영 커밋: 44f8891 Fix critical markdown lint configuration

2) 배포/검증 흐름

1. 작성자는 템플릿(docs/templates/doc-template.md) 기반으로 문서 작성
2. 로컬에서 npm run docs:build 확인
3. PR 생성 시 체크리스트 작성 (.github/pull_request_template.md)
4. CI(Docs Quality Check) 확인
5. main 머지 후 Cloudflare 배포 로그 및 URL 확인

3) 이번 세션 개발 이력

3.1 저장소 위치 정리

• GitHub 저장소: https://github.com/seihwanMoon/mVitePress
• 로컬 표준 위치: D:\CODE\AICODE\mVitePress
• 초기 임시 위치였던 C:\Users\ictpt590\Documents\New project는 더 이상 기준 작업 폴더가 아님

3.2 문서 구조 변경

• docs/operations/qmd 사용 가이드 (CMDS).md를 docs/operations/obsidian/qmd 사용 가이드 (CMDS).md로 이동
• 이동은 내용 변경 없는 100% rename으로 반영됨
• 반영 커밋: cb16869 Move qmd guide into obsidian operations

3.3 사이드바 폴더 트리화

• 기존 문제:
  • guide/concepts/, guide/practice/, operations/obsidian/ 같은 하위 폴더가 사이드바에서 최상위 그룹처럼 평탄하게 표시됨
• 변경:
  • docs/.vitepress/sidebar.mjs를 추가하여 docs/ 실제 폴더 구조를 재귀적으로 읽음
  • 폴더는 VitePress sidebar group으로 만들고 collapsed: true를 적용
  • docs/.vitepress/config.mts는 sidebar 생성 모듈을 import해서 사용
  • tests/sidebar-structure.test.mjs로 guide > concepts/practice, operations > obsidian 중첩 구조를 검증
• 반영 커밋: 2b789bf Make sidebar follow docs folder tree

3.4 markdownlint critical 설정 수정

• GitHub Actions 실패 원인:
  • markdownlint-cli2 --config .markdownlint-critical.jsonc ...를 실행해도 루트의 기본 .markdownlint.jsonc가 자동 발견되어 병합됨
  • 그 결과 default: false인 critical 설정 대신 전체 스타일 규칙이 실패로 처리됨
  • qmd 문서의 MD013, MD060, MD032, MD040 등 36개 오류가 CI fail로 표시됨
• 변경:
  • .markdownlint.jsonc 삭제
  • package.json의 lint:md, lint:md:style 검사 범위를 CI와 동일하게 명시
  • critical lint는 .markdownlint-critical.jsonc만 기준으로 fail 처리
  • style lint는 .markdownlint-style.jsonc 기준 warning-only 운영 유지
• 반영 커밋: 44f8891 Fix critical markdown lint configuration

4) 주요 설정 파일

• 사이트 구성: docs/.vitepress/config.mts
• 사이드바 생성: docs/.vitepress/sidebar.mjs
• 사이드바 구조 테스트: tests/sidebar-structure.test.mjs
• 문서 품질 CI: .github/workflows/docs-quality.yml
• Cloudflare 배포: .github/workflows/deploy-cloudflare.yml
• markdown 규칙(치명): .markdownlint-critical.jsonc
• markdown 규칙(스타일): .markdownlint-style.jsonc
• 로컬 훅: .githooks/pre-commit

5) 알려진 운영 포인트와 주의점

• markdownlint 스타일 규칙은 warning-only로 운영되어 PR 피로도를 낮춤
• link-check는 빌드 산출물(docs/.vitepress/dist/**/*.html) 기준으로 검사
• Cloudflare 시크릿이 없으면 배포 step은 skip됨(실패 아님)
• main에 docs/**, package.json, .github/workflows/deploy-cloudflare.yml 변경을 push하면 Cloudflare Pages 배포 워크플로우가 자동 실행됨
• 로컬에서 npm install을 실행하면 package-lock.json이 생성됨
  • 현재 저장소에는 lockfile이 tracked 상태가 아님
  • lockfile을 정책적으로 도입할지 결정하기 전까지는 커밋에 포함하지 않음
• npm run lint:md는 critical lint만 검사하며 CI fail 기준임
• npm run lint:md:style은 스타일 품질 확인용이며 CI에서는 warning-only임
• qmd 운영 문서는 아직 스타일 lint 기준을 모두 만족하지 않지만 critical lint는 통과함
• pre-commit 훅은 npm run lint:md만 실행하므로 현재 기준으로 정상 커밋 가능

6) 현재 검증된 명령

node --test tests/sidebar-structure.test.mjs
npm run lint:md
npm run docs:build

최근 확인 결과:

• sidebar 구조 테스트 통과
• critical markdown lint Summary: 0 error(s)
• VitePress production build 통과

7) 다음 담당자 액션 아이템

• [ ] GitHub Actions 새 run에서 Docs Quality Check가 통과하는지 확인
• [ ] Cloudflare Pages 배포가 새 main push를 반영했는지 확인
• [ ] package-lock.json을 도입할지 결정
• [ ] qmd 운영 문서의 style lint 경고를 별도 정리 작업으로 분리
• [ ] PR/배포 실패 사례를 docs/updates.md에 주간 단위로 기록
• [ ] docs/guide/writing-template.md를 월 1회 업데이트
• [ ] 문서 사용량(조회수/검색유입) 기반으로 IA 개선 우선순위 재정의
• [ ] 필요 시 GitHub Pages 수동 워크플로우 정리(유지/폐기 결정)

8) 다음 세션 재시작 명령어

cd /d D:\CODE\AICODE\mVitePress
git status --short --branch
git pull --ff-only origin main
npm install
npm run prepare:githooks
npm run docs:build
npm run lint:md
npm run docs:dev -- --host 127.0.0.1

로컬 사이트:

http://127.0.0.1:5173/

9) 다음 세션 첫 프롬프트 예시

D:\CODE\AICODE\mVitePress에서 이어서 작업해줘.
먼저 git status, 최근 커밋, GitHub Actions/Cloudflare 배포 상태를 확인하고,
package-lock.json 처리 방침과 qmd 문서 style lint 정리 여부를 판단해줘.