mdsvr용 마크다운 스킬
mdsvr과 함께 사용할 완전하고 유효하며 여러 파일로 구성된 마크다운 문서 세트를 생성합니다. 서버 모드와 정적 내보내기를 모두 지원합니다.
이 스킬이 실행되면, 여러 개의 .md 파일을 생성하여 일관된 문서 사이트를 구성하며, 모든 mdsvr 규칙을 엄격히 따릅니다.
1단계 — 요청 이해
파일을 생성하기 전에 사용자의 요청에서 다음을 추출합니다.
- 주제 / 제품 이름 — 무엇에 대한 문서인가요?
- 대상 독자 — 개발자, 최종 사용자, 운영팀 등
- 범위 — 몇 페이지 / 섹션이 필요한가요?
- 언어 — 베트남어, 영어, 또는 이중 언어인가요?
- 다이어그램 필요 여부 — 필요한 경우
references/rules/mermaid.md를 참조하여 구문 규칙을 확인하세요.
이 중 명확하지 않은 것이 있으면, 진행 전에 한 가지 집중된 질문을 하세요.
2단계 — 파일 구조 설계
콘텐츠를 작성하기 전에 논리적인 계층 구조를 설계하세요. 일반적인 mdsvr 문서 사이트 구조:
docs/
├── README.md ← 홈페이지 (필수)
├── 01-getting-started/
│ ├── README.md ← 섹션 인덱스
│ ├── 01-installation.md
│ ├── 02-quickstart.md
│ └── 03-configuration.md
├── 02-guides/
│ ├── README.md
│ ├── 01-basic-usage.md
│ └── 02-advanced.md
├── 03-api-reference/
│ ├── README.md
│ └── 01-endpoints.md
└── 04-troubleshooting.md
사용자의 주제에 맞게 구조를 조정하세요. 필요에 따라 규모를 조절합니다.
3단계 — mdsvr 파일 및 링크 규칙 적용 (필수)
3.1 파일 명명 규칙
| 규칙 | ❌ 잘못된 예 | ✅ 올바른 예 |
|---|---|---|
| 이름 중간에 점(.) 사용 금지 | 0.1.quickstart.md | 01-quickstart.md |
| 이름 중간에 점(.) 사용 금지 | config.v2.md | config-v2.md |
| 케밥 케이스 사용 | GettingStarted.md | getting-started.md |
| 순서를 위한 숫자 접두사 사용 | guide.md (사이드바) | 01-guide.md |
| 설명적인 이름 사용 | page1.md | installation.md |
| 디렉토리 인덱스 파일 | index.md | README.md |
3.2 링크 구조 규칙
| 규칙 | ❌ 잘못된 예 | ✅ 올바른 예 |
|---|---|---|
| 상대 경로만 사용 | [Guide](/docs/guide) | [Guide](./guide) |
링크에 .md 확장자 사용 금지 | [Setup](./setup.md) | [Setup](./setup) |
| README가 아닌 디렉토리에 링크 | [Start](./01-getting-started/README) | [Start](./01-getting-started) |
| 앵커 링크는 제목과 일치해야 함 | [See](#install-steps) (해당 제목이 없을 경우) | 정확히 일치해야 함 |
3.3 제목 구조 규칙
| 규칙 | ❌ 잘못된 예 | ✅ 올바른 예 |
|---|---|---|
| 모든 페이지에 H1 필요 | (페이지가 H2로 시작) | # Page Title 첫 번째 제목으로 |
| 제목 수준 건너뛰기 금지 | H1 → H3 | H1 → H2 → H3 |
| 제목은 설명적이어야 함 | ## Section 1 | ## Installation Requirements |
4단계 — 모든 파일에 프론트매터 적용
각 .md 파일에는 SEO 및 mdsvr 메타데이터를 위한 YAML 프론트매터가 포함되어야 합니다.
---
title: "Page Title"
description: "이 페이지 내용에 대한 한 문장 설명."
---
5단계 — 콘텐츠 가이드라인
README.md (홈페이지) — 필수
- docs 폴더의 루트에 반드시 존재해야 합니다.
- 다음을 포함: 프로젝트 개요, 모든 섹션으로의 빠른 탐색 링크.
- 적절하다면 환영 콜아웃을 사용하세요.
섹션 README.md (디렉토리 인덱스)
- 섹션에서 다루는 내용을 요약합니다.
- 섹션의 모든 페이지를 상대 링크와 함께 나열합니다.
콘텐츠 페이지
- 페이지당 하나의 집중된 주제를 다룹니다.
- 간단한 소개 단락으로 시작합니다.
- 적절한 경우 MDX 구성 요소를 사용합니다:
:::note,:::warning,:::tip,:::danger(콜아웃)- 단계별 절차를 위한 번호 목록
- 상대 경로를 사용하여 관련 페이지로 자유롭게 링크합니다.
- 유용한 경우 "다음 단계" 또는 "관련 항목" 섹션으로 끝냅니다.
6단계 — Mermaid 다이어그램 (필요한 경우)
문서에 다이어그램(아키텍처, 흐름, 시퀀스, ERD, 상태 머신 등)이 도움이 되는 경우, 관련 .md 파일에 Mermaid 다이어그램을 인라인으로 포함합니다.
다이어그램을 생성하기 전에 전체 구문 참조 및 생성 규칙을 위해
references/rules/mermaid.md를 읽으세요. 해당 파일의 모든 규칙은 필수입니다.
빠른 체크리스트 (mermaid.md에서):
- 가장 적절한 다이어그램 유형을 선택하세요. 기본적으로
flowchart를 사용하지 마십시오. - 순서도에서 방향을 항상 선언하세요:
flowchart TD또는flowchart LR. - 노드 ID: 문자, 숫자, 밑줄만 사용하세요.
-,.,(,)는 사용할 수 없습니다. - 공백이 있는 노드 레이블은 큰따옴표를 사용하세요:
A["My Label"]. - 서브그래프에는 명시적인 ID가 있어야 합니다:
subgraph myid["Label"]. - 시퀀스 다이어그램: 메시지 전에 모든
participant줄을 선언하세요. - 사용자가 명시적으로 요청하지 않는 한 하드코딩된 색상이나 스타일을 사용하지 마십시오.
- 의미를 전달하기 위해 색상 대신 이모지를 사용하세요.
- 코드 블록당 하나의 다이어그램; 출력하기 전에 구문을 검증하세요.
7단계 — 파일 생성 및 전달
create_file을 사용하여 각 .md 파일을 파일 시스템에 작성합니다. 그런 다음 모든 파일을 압축하고 present_files를 호출하여 사용자가 결과를 다운로드할 수 있도록 합니다.
7.1 각 파일 작성
계획된 구조의 모든 파일에 대해 /mnt/user-data/outputs/<project-name>/ 아래의 전체 경로로 create_file을 호출합니다.
/mnt/user-data/outputs/my-project/README.md
/mnt/user-data/outputs/my-project/01-getting-started/README.md
/mnt/user-data/outputs/my-project/01-getting-started/01-installation.md
...
각 호출에서 완전하고 최종적인 콘텐츠를 작성하세요. 플레이스홀더를 작성하지 마십시오.
7.2 압축 및 전달
모든 파일이 작성된 후, 출력 폴더를 압축하고 present_files를 호출합니다.
cd /mnt/user-data/outputs
zip -r my-project-docs.zip my-project/
그런 다음 .zip 파일의 경로와 함께 present_files를 호출합니다.
7.3 채팅 요약
present_files 후, 채팅에 다음을 포함한 짧은 메시지를 작성합니다.
- 파일 트리 — 생성된 전체 디렉토리 구조를 표시합니다.
- 서빙 방법 — 한 줄 명령어:
npx mdsvr ./my-project또는mdsvr ./my-project. - 페이지 수 — 예: "3개 섹션에 걸쳐 8페이지 생성됨."
빠른 참조 — 피해야 할 일반적인 실수
❌ 절대 경로 링크: [Page](/docs/page)
✅ 상대 경로: [Page](./page)
❌ 링크에 .md 확장자: [Page](./page.md)
✅ 확장자 없음: [Page](./page)
❌ README 파일에 링크: [Section](./01-section/README)
✅ 디렉토리에 링크: [Section](./01-section)
❌ 파일명에 점: 01.quickstart.md
✅ 하이픈 구분자: 01-quickstart.md
❌ H1 누락: ## Introduction (첫 번째 제목이 H2)
✅ H1으로 시작: # Introduction
❌ 제목 수준 건너뜀: # Title → ### Sub (H2 생략)
✅ 적절한 계층: # Title → ## Section → ### Subsection
❌ 프론트매터 없음: (파일이 #으로 직접 시작)
✅ 프론트매터 있음: --- title: "..." description: "..." ---
참조 파일
references/rules/mermaid.md— 19가지 다이어그램 유형에 대한 전체 Mermaid v11 구문 참조. 문서에 다이어그램이 필요할 때마다 이 파일을 읽으세요.