문서 사이트의 MDX 페이지를 규칙대로 오류 없이 쓰기

## 쓰기 전에 문서 사이트의 구조 파악하기 저장소를 느슨한 Markdown 파일 모음이 아니라 스키마 기반 문서 애플리케이션으로 취급하십시오. 사이트 생성기, 문서 테마, 구성 요소 프레임워크, 패키지 관리자, 런타임 버전, 배포 대상을 식별하십시오. 저장소에 고정된 재현 가능한 명령으로 종속성을 설치하십시오. 런타임과 패키지 관리자 버전을 저장소 메타데이터와 일치시키십시오. 관례적인 이름을 가정하지 말고 기본 기여 브랜치를 확인하십시오. 사용자용 페이지, 재사용 가능한 파셜, 변경 로그, 용어집 데이터, 제품 메타데이터, 기타 구조화된 컬렉션을 구분하십시오. 사용자 지정 구성 요소, 콘텐츠 스키마, Markdown 플러그인, 코드 강조 플러그인, 아이콘, 자산, 스타일, 동적 경로를 각각 지정된 계층에 유지하십시오. 정적 공개 파일과 사이트 생성기에서 처리하는 이미지를 다르게 취급하십시오. 중앙 구성 요소 내보내기 모듈을 MDX용 공개 가져오기 인터페이스로 사용하십시오. 컬렉션 스키마를 허용되는 필드와 값 유형에 관한 정본으로 유지하십시오. 생성된 스킬 또는 참조 디렉터리를 빌드 산출물로 취급하십시오. 생성된 디렉터리를 편집하거나 무시 대상으로 지정된 생성 콘텐츠를 커밋하지 마십시오. 전문 검토 봇이나 배포 워커를 변경하기 전에 중첩된 지침을 읽으십시오. 저장소별 스타일, 구성 요소, 절차 참조 자료를 정본 지침으로 사용하십시오. 일반적인 Markdown 습관이 사이트의 MDX 및 스키마 규칙보다 우선하게 두지 마십시오. ## 페이지를 알맞은 폴더에 두고 파일 이름 규칙 지키기 사용자용 문서 페이지는 제품 또는 주제 디렉터리 아래에 두십시오. 재사용 가능한 스니펫은 파셜 컬렉션에 두십시오. 변경 로그 항목은 해당 제품 또는 주제의 하위 디렉터리에 두십시오. 용어집 용어와 기타 구조화된 메타데이터는 각 스키마가 소유하는 컬렉션에 두십시오. 사이트에서 요구한다면 탐색 가능한 모든 콘텐츠 폴더에 인덱스 페이지가 있어야 합니다. 단어를 대시로 구분한 소문자 파일 이름을 사용하십시오. 콘텐츠 디렉터리를 명시적으로 허용된 텍스트 및 데이터 확장자로 제한하십시오. 일반적으로 허용되는 유형은 MDX, JSON, YAML, 일반 텍스트입니다. 지원되지 않는 파일을 숨기지 말고 확장자 검증으로 허용 목록을 적용하십시오. 스키마가 스캔하는 콘텐츠 디렉터리에 이미지나 임의의 바이너리를 두지 마십시오. 처리 가능한 이미지는 최적화용 전용 자산 트리에 두십시오. 진정한 정적 파일은 변경 없이 제공해야 할 때만 공개 트리에 두십시오. 디렉터리 이름을 기존 제품 메타데이터와 일치시키십시오. 알 수 없는 제품 키에 대해 변경 로그나 컬렉션 하위 디렉터리를 만들지 마십시오. 병렬 콘텐츠 위치를 새로 만들지 말고 확립된 컬렉션 경계를 보존하십시오. 페이지를 이동할 때는 해당 페이지로 들어오는 링크, 탐색 메타데이터, 리디렉션, 관련 파셜 참조를 업데이트하십시오. ## 사이트가 요구하는 페이지 설정(프런트매터) 채우기 모든 문서 페이지에 해당 컬렉션 스키마를 충족하는 프런트매터 블록을 제공하십시오. 간결한 페이지 제목을 제공하십시오. 선택한 콘텐츠 유형에서 요구할 때마다 검색 설명을 제공하십시오. 저장소에서 허용하는 열거형에서 페이지 유형을 선택하십시오. 일반적인 유형에는 `concept`, `configuration`, `example`, `FAQ`, `getting started`, `how-to`, `integration`, `implementation`, `overview`, `reference`, `release notes`, `solution`, `troubleshooting`, `tutorial`이 있습니다. 스키마에서 제공할 때는 `design guide`, `learning unit`, `navigation`, `reference architecture`, `video`와 같은 특수 유형을 사용하십시오. 명시적인 순서가 필요할 때만 사이드바 순서를 사용하십시오. 탐색 문구가 페이지 제목과 달라야 할 때만 사이드바 레이블을 사용하십시오. 기존 메타데이터 키를 통해 제품이나 주제를 참조하십시오. 튜토리얼 콘텐츠에는 문서화된 난이도 열거형을 사용하십시오. 필수 연-월-일 형식으로 검토 날짜를 기록하십시오. 스키마 필드나 열거형 값을 만들어 내지 마십시오. YAML 들여쓰기와 목록 구조를 유효하게 유지하십시오. 컬렉션 정의나 스키마를 변경한 후에는 콘텐츠 컬렉션 유형을 다시 생성하십시오. 육안 검사에 의존하지 말고 데이터 파일을 해당 스키마에 따라 검증하십시오. 페이지의 목적, 제품, 제목 또는 검토 상태가 변경되면 페이지 메타데이터를 동기화하십시오. ## 문법 오류 없이 빌드되는 MDX 페이지 쓰기 저장소의 정본 작성 및 서식 가이드를 따르십시오. MDX를 Markdown에 더 엄격하게 파싱되는 내장 구성 요소 언어를 더한 형식으로 취급하십시오. 중괄호와 꺾쇠괄호 문자를 일반 문장으로 사용할 때는 이스케이프하거나 코드 서식을 적용하십시오. MDX는 일반 문장 안에서도 해당 문자를 표현식이나 구성 요소로 해석한다는 점을 기억하십시오. 페이지에서 사용하는 모든 구성 요소를 가져오십시오. 가져오기는 프런트매터 바로 뒤이자 페이지 콘텐츠 앞에 배치하십시오. 지원되는 구문 강조 언어 식별자만 사용하십시오. 일반적인 터미널 출력에는 저장소의 일반 텍스트 언어 식별자를 사용하십시오. 코드 펜스에서는 소문자 언어 식별자를 사용하십시오. 사이트 내부 링크에는 루트 기준 절대 경로를 사용하십시오. 내부 대상에 전체 프로덕션 URL을 사용하지 마십시오. 지원되지 않는 상대 페이지 링크를 사용하지 마십시오. 제목 수준을 순서대로 유지하고 중간 수준을 건너뛰지 마십시오. 복사 가능한 명령에서 셸 프롬프트 기호를 생략하십시오. 작업, 위치, 예상 결과가 명확한 간결한 단계를 작성하십시오. 여러 페이지에 동일하게 유지 관리되는 텍스트가 필요하면 재사용 가능한 설명을 파셜에 두십시오. 코드 예제를 문서화된 API와 현재 제품 동작에 따라 검증하십시오. ## 구성 요소와 이미지를 규칙대로 쓰고 리디렉션은 필요할 때만 바꾸기 MDX 구성 요소는 저장소의 중앙 구성 요소 일괄 내보내기 모듈을 통해서만 가져오십시오. 필수 속성과 사용 제약은 구성 요소 문서를 참조하십시오. 지원되는 공개 구성 요소가 있다면 구성 요소 내부 구현을 콘텐츠에 복사하지 마십시오. 새 구성 요소 코드는 지정된 구성 요소 디렉터리에 두십시오. 필수 사용자 지정 요소 접두사와 케밥 표기법 명명 규칙을 사용하십시오. 각 구성 요소를 해당 구성 요소의 이름을 딴 디렉터리에 유지하십시오. 필수 접미사가 붙은 PascalCase 클래스 이름을 사용하십시오. 새로운 접두사 규칙을 적용하기 위해서만 적용 제외된 레거시 요소의 이름을 바꾸지 마십시오. 소스 이미지를 해당 제품 또는 주제의 최적화된 자산 디렉터리에 유지하십시오. 로컬 전체 빌드를 통해 이미지 경로를 검증하십시오. 페이지 이동이나 URL 마이그레이션에서 요구할 때만 리디렉션을 수정하십시오. 리디렉션 소스 경로는 필수 슬래시 또는 허용되는 파일 접미사나 와일드카드 접미사로 끝내십시오. 리디렉션 소스 URL에 프래그먼트를 넣지 마십시오. 검토 전에 리디렉션 루프를 탐지하십시오. 리디렉션 파일이 변경될 때마다 전용 리디렉션 검증 도구를 실행하십시오. 구성 요소, 이미지, 링크, 리디렉션 변경을 페이지의 의도된 범위 안으로 제한하십시오. ## 로컬과 CI에서 필요한 검사를 통과한 뒤 완성 알리기 콘텐츠를 변경할 때마다 스키마 및 유형 검사를 실행하십시오. 로컬 전체 빌드로 MDX 파싱, 이미지 경로, 내부 링크를 검증하십시오. 로컬 전체 검증 빌드 중에는 내부 링크 검사를 활성화하십시오. 제약이 있는 CI 안에서 타임아웃되는 것으로 알려진 전체 빌드를 실행하지 마십시오. CI에서는 축소된 안전 집합으로 유형 검사, 린트, 서식 검사를 실행하십시오. 코드 변경에는 저장소의 전체 테스트 스위트도 실행하십시오. 커밋하기 전에 편집한 모든 파일의 서식을 지정하십시오. 자동 수정 후에는 저장소의 서식 검사를 실행하십시오. 리디렉션 구성에 변경이 있을 때만 리디렉션 검증을 실행하십시오. 스키마나 컬렉션 변경 후에는 컬렉션 유형 동기화를 실행하십시오. 가능하면 로컬 전체 검증 순서를 CI 파이프라인과 일치시키십시오. CI에서 파일 확장자, 유형, 린트, 서식, 빌드와 링크, 리디렉션, 테스트를 검사할 것으로 예상하십시오. 스타일 스캐너 경고가 심각한 실패가 아니더라도 검토 증거로 취급하십시오. 직접 관련된 검증 게이트가 누락된 동안에는 페이지가 준비되었다고 보고하지 마십시오. CI 환경의 한계와 실제 콘텐츠 실패를 구분하십시오. 수정 편집을 할 때마다 직접 영향받는 검사를 다시 실행하십시오. ## 디렉터리 항목마다 도구로 만든 ID를 붙이고 바꾸지 않기 모든 디렉터리 항목 데이터 파일의 필수 첫 줄 위치에 고유하고 안정적인 식별자를 지정하십시오. 저장소에서 정한 정확한 식별자 길이와 혼동을 줄인 문자 집합을 사용하십시오. 6문자 방식에서는 생성된 모든 값이 정확히 6자인지 검증하십시오. 방식에서 요구한다면 시각적으로 모호한 문자를 제외하십시오. 이름에서 식별자를 도출하지 말고 무작위로 생성하십시오. 식별자를 직접 만들거나 추측하거나 복사하지 마십시오. 저장소의 식별자 도구를 사용하여 전체 컬렉션을 검사하십시오. 누락되거나 형식이 잘못되거나 중복된 식별자에는 도구의 수정 모드를 사용하십시오. 표시 이름이나 파일 이름이 변경되어도 기존의 유효한 식별자를 유지하십시오. 확인된 검증 오류를 복구할 때만 기존 식별자를 변경하십시오. 필수 YAML 확장자 한 종류만 일관되게 사용하십시오. 식별자 생성을 편집상의 선택이 아니라 자동화 작업으로 취급하십시오. 전체 디렉터리 컬렉션에서 고유성을 확인하십시오. 식별자 생성과 스키마 검증을 CI에 유지하십시오. 생성된 변경을 커밋하기 전에 도구의 diff를 검토하십시오. 도구가 성공한 후에는 생성된 식별자를 수동으로 조정하지 마십시오. ## 작업별 안내와 커밋 규칙에 따라 변경 보내기 작성, 편집, 예제 검토, 변경 로그 추가 또는 풀 리퀘스트 준비 전에 저장소의 기여 라우터를 사용하십시오. 해당 라우터에서 선택한 작업별 참조 자료를 따르십시오. 전문 봇의 코드, 워크플로 라우팅, 상태 또는 배포를 변경하기 전에 해당 봇의 로컬 지침을 읽으십시오. 도구별 심볼릭 링크가 커밋된 공유 에이전트 구성을 가리키도록 유지하십시오. 설명이 작업과 일치할 때만 저장소 스킬을 로드하십시오. 문장과 서식에 관한 결정에는 정본 스타일 가이드를 사용하십시오. 속성, 예제, 필수 패턴에는 구성 요소 카탈로그를 사용하십시오. 단계별 지침에는 절차 가이드를 사용하십시오. 코드 변경의 영향을 받는 각 런타임 워크스페이스에서 테스트를 실행하십시오. 워커, 서버 런타임, 사이트 생성기 테스트를 서로 구분하십시오. 저장소에서 허용하는 제품 또는 유형 접두사 형식으로 커밋을 작성하십시오. 커밋 설명을 사용자에게 보이는 수정 또는 기술적 수정에 구체적으로 맞추십시오. 관련 없는 서식, 생성 콘텐츠 또는 제품 변경을 포함하지 마십시오. 콘텐츠, 스키마, 가져오기, 자산, 링크, 리디렉션, 테스트, 기여 규칙이 모두 일치할 때만 승인하십시오.