NextPDF 문서 구성 방식

한눈에 보기

NextPDF 문서는 고정된 규약에 따라 확장됩니다. 모든 페이지는 하나의 주제, 하나의 Diataxis 모드, 하나의 페이지 종류를 가집니다. 모든 페이지 종류에는 필수 레벨 2 제목 집합이 있습니다. 몇 가지 매니페스트와 게이트가 문서가 확장되는 동안 구조를 올바르게 유지합니다.

이 페이지는 이 시스템의 구조를 설명하여 기여 내용이 올바른 위치에 배치되도록 돕습니다. 정확한 제목 목록, 인용 규칙, 단계별 게이트 연결 절차를 포함한 완전한 규범 규약은 내부 거버넌스 문서 docs/style/expansion-standard.md에 있습니다. 먼저 이 페이지를 읽고, 작성할 때 해당 문서를 참고하십시오.

페이지 종류 선택

페이지를 추가할지 아니면 기존 페이지를 확장할지 결정하려면 다음 규칙을 순서대로 적용하십시오.

독자가 기존 페이지에서 기대하기 어려운 별개의 주제라면 새 페이지를 추가하십시오.
기존 페이지가 이미 다루는 주제를 완성하는 내용이라면 해당 페이지를 확장하십시오.
설치, 빠른 시작, 작업 페이지를 지나치게 길게 만들 만큼 깊은 세부 내용이라면 별도 페이지로 옮기고 그 페이지로 링크하십시오.
그 외의 경우에는 기존 페이지를 확장하십시오.

페이지가 필요하다고 판단했으면 해당 페이지의 Diataxis 모드를 설정하십시오. 이 모드가 페이지 종류를 결정합니다.

튜토리얼은 학습자를 가르치므로 레시피 형태로 작성한 작업 가이드를 사용하십시오.
방법 안내(How-to)는 숙련된 독자가 작업을 완료하도록 돕므로 작업 가이드, 서버 API 가이드 또는 SDK 가이드를 사용하십시오.
레퍼런스는 정확한 사실을 제시하므로 API 레퍼런스나 색인 페이지를 사용하십시오.
설명(Explanation)은 이해를 형성하므로 개발자 가이드나 프리미엄 기능 가이드를 사용하십시오.

평이한 언어는 별도의 모드가 아니라 모든 모드의 기본 원칙입니다.

페이지 종류 카탈로그

문서 규약에서 인정하는 종류는 다음과 같습니다. 페이지에 API 표가 있는 경우에는 항상 기존 종류를 재사용하고, API 표가 없는 페이지에 한해서만 새 레이블 전용 종류를 도입하십시오.

색인 종류: section-index, api-index, extension-index.
레퍼런스 종류: api-reference. 서버 및 Python SDK 레퍼런스를 포함하여 표준 API 표가 있는 모든 페이지에 이 종류를 재사용하십시오.
설명 종류: developer-guide. 서버 및 Python SDK 가이드를 포함하여 아키텍처, 수명 주기, 확장 지점에 대한 설명에 이 종류를 재사용하십시오.
새 레이블 전용 종류: premium-feature-guide와 task-guide이며, 둘 다 API 표가 없는 페이지를 위한 것입니다.

모든 페이지는 ## At a glance(으)로 시작합니다. 모든 api-reference 페이지는 공유 API 표와 Development notes 제목을 포함합니다. 필수 제목은 정확히 레벨 2이며 각각 별도의 줄에 위치합니다. 그 아래에 제목을 더 추가할 수 있습니다.

작성 체크리스트

페이지를 작성할 때는 다음 두 체크리스트를 모두 충족하십시오. 내부 표준은 각 항목을 규범적으로 기술하고 그 근거가 되는 표준을 링크합니다.

개발자 친화성:

실행 가능한 예제는 examples/ 또는 tests/Cookbook에서 가져오고, 각 펜스 블록에 title= 정보 문자열을 넣으십시오.
전제 조건은 프런트매터와 도입부에 기술하십시오.
출력을 생성하는 모든 샘플에 대해 예상 출력을 보여 주십시오.
블록은 복사해서 붙여 넣을 수 있도록 유지하십시오. 블록당 하나의 언어를 사용하고, 처음 사용할 때 전체 이름을 쓰며, 끝에 프롬프트 문자를 두지 마십시오.
기본적으로 안전한 코드를 보여 주십시오. 프로덕션 샘플은 가장 구체적인 NextPDF 예외를 대상으로 try/catch를 사용하며 빈 catch는 절대 사용하지 않습니다.
이어 읽을 링크로 마무리하고 프런트매터 related:를 설정하십시오.

번역 준비성:

기계 번역 결과가 장황해지지 않도록 한 문장에는 한 가지 생각만 담아 작성하십시오.
대부분의 대상 언어에서는 길이가 늘어나므로 제목과 레이블을 짧게 유지하십시오.
관용 표현을 피하십시오.
심볼 이름, 구성 키, CLI 플래그, 예외 이름은 코드 서식으로 유지하십시오. PDF/A-4, PAdES, eIDAS와 같은 표준 이름은 절대 번역하지 않습니다.
프런트매터의 i18n_ready와 xliff_segments를 정직하게 설정하고 Unicode NFC로 작성하십시오.

어조, 코드 샘플, 용어, 인용 스타일에 대해서는 내부 표준에서 참조하는 승인된 스타일 오버라이드 시트를 따르십시오.

게이트 연결

새 페이지는 순서가 정해진 절차에 따라 연결됩니다.

프런트매터가 사이트 스키마와 일치하도록 페이지를 스캐폴딩하십시오.
페이지 종류의 필수 제목에 맞춰 본문을 작성하십시오.
새 항목으로 { path, owner, kind, headings[] }를 docs/manual-contract.json에 추가하십시오. 경로는 src/content/docs에 대한 상대 경로이며, 슬래시를 사용하고, 선행 슬래시와 ..를 포함하지 않습니다.
API 레퍼런스의 경우, 페이지의 심볼을 docs/api-coverage-manifest.json에 추가하십시오. 각 심볼은 페이지에 나타나야 하며 소스에 존재해야 합니다.
페이지가 새 소스 리포지토리에서 오는 경우에만 docs/source-manifest.json을 업데이트하십시오.
올바른 사이드바 그룹에 명시적 항목으로 astro.config.mjs에 페이지를 추가하십시오.
영어 전용 페이지의 경우, 17개 로케일 셀을 모두 missing(으)로 설정한 로케일 커버리지 행을 추가하십시오.
문서 게이트, 빌드, 성능 예산을 실행하십시오.

사이트 소유 페이지는 src/content/docs 아래에 위치하고, owner를 nextpdf-docs(으)로 설정하며, 집계 마커를 절대 포함하지 않습니다. 집계된 페이지는 소스 리포지토리에서 오며, 게시 플래그는 소스 프런트매터에 있으므로 여기서가 아니라 그곳에서 편집하십시오.

함께 보기

통합: 여러 패키지에 걸친 문서 구조를 보여 주는 가장 큰 실제 예시입니다.
내부 거버넌스 문서 docs/style/expansion-standard.md는 완전한 규약을 담고 있습니다. 모든 페이지 종류에 대한 정확한 제목 목록, 인용 규칙, 전체 게이트 연결 절차가 포함됩니다.