README PDF 변환기

README.md 파일은 프로젝트, 리포지토리, 패키지, 애플리케이션, 데이터셋 또는 워크플로우를 설명하는 Markdown 문서입니다.

README 파일에는 일반적으로 다음이 포함됩니다:

• 프로젝트 제목 및 요약;
• 설치 안내;
• 사용 예시;
• 명령줄 코드 조각;
• 설정 예시;
• 기능 목록;
• 작업 목록;
• 표;
• 스크린샷;
• 배지;
• 기여 안내;
• 라이선스 또는 지원 정보;
• 문서 및 릴리스 링크.

.md 확장자는 파일이 Markdown으로 작성되었음을 의미합니다. 이를 PDF로 변환하면 편집 가능한 버전의 Markdown 소스를 유지하면서 고정된 문서를 생성할 수 있습니다.

PDF는 README가 원래 리포지토리를 벗어나야 하거나 페이지 기반 문서로 검토되어야 할 때 유용합니다.

일반적인 이유는 다음과 같습니다:

• 클라이언트 또는 이해관계자와 프로젝트 문서 공유;
• 이메일 또는 티켓에 기술 요약 첨부;
• 검토 또는 승인을 위한 문서 제출;
• 특정 시점의 리포지토리 오프라인 스냅샷 생성;
• 설치 안내서 또는 운영 런북 인쇄;
• 릴리스 문서 보관;
• GitHub를 사용하지 않는 독자에게 README 배포;
• 고정된 레이아웃에서 긴 코드, 수식, 다이어그램 및 표 검토.

원본 README는 유지 관리 가능한 소스로 남아 있어야 합니다. README가 변경된 후 PDF를 다시 생성하십시오.

SolConverter는 README 파일에서 일반적으로 사용되는 Markdown 요소를 지원합니다.

지원되는 요소는 다음과 같습니다:

• ATX 및 Setext 제목;
• 굵게, 기울임꼴 및 취소선 텍스트;
• 순서 있는 목록 및 순서 없는 목록;
• 중첩된 목록;
• GFM 작업 목록;
• 인용구;
• Markdown 링크 및 자동 링크;
• 인라인 코드;
• 백틱 또는 물결표를 사용한 펜스 코드 블록;
• 코드 펜스 언어 레이블;
• 정렬 기능이 포함된 GFM 표;
• 안전한 원시 HTML 표;
• details 및 summary 섹션;
• kbd, sub, sup, figure, 및 figcaption;
• 제목 앵커;
• 소스 시작 부분의 YAML 프런트 매터(front matter).

달러 기호나 LaTeX 스타일의 구분 기호가 포함된 코드 펜스는 수식으로 해석되지 않고 코드로 유지됩니다.

README 파일에는 설치 명령, 설정 파일, API 예시, 환경 변수 및 소스 코드 스니펫이 포함되는 경우가 많습니다.

SolConverter는 코드 펜스 언어가 인식되면 Highlight.js를 사용하여 구문 강조를 적용합니다. 인식되지 않는 언어는 원본 소스를 안전하게 유지합니다.

코드 블록은 전용 고정폭 글꼴과 주변 설명과 분리되는 인쇄 스타일을 사용합니다. 코드는 우횡서(RTL) README에서도 좌횡서(LTR)로 유지됩니다.

기술용 README에는 공식, 행렬, 과학적 표기법, 확률 식 또는 화학식이 포함될 수 있습니다.

SolConverter는 일반적인 Markdown 수식 구분 기호, AMS 수식 환경, Presentation MathML, 기본 Content MathML 및 \ce{...}로 작성된 화학식에 대해 MathJax SVG 출력을 지원합니다.

지원되는 수식은 다음과 같습니다:

• $...$ 및 \(...\) 인라인식;
• $$...$$ 및 \[...\] 디스플레이식;
• 수식 및 정렬(alignment) 환경;
• 분수, 제곱근, 합, 적분, 극한 및 행렬;
• 문서 범위 매크로;
• 줄 바꿈이 필요한 긴 덧셈 식.

수식은 PDF 내에서 선명함을 유지하기 위해 SVG로 렌더링됩니다. 잘못된 수식은 README의 나머지 부분을 자동으로 중단하지 않고 로컬에서 대체 처리될 수 있습니다.

README 파일은 아키텍처, 시퀀스, 상태, 워크플로우 또는 컴포넌트 관계를 설명하기 위해 다이어그램을 자주 사용합니다.

지원되는 Mermaid 펜스 블록은 로컬에서 SVG로 렌더링됩니다. ZenUML 또한 번들 Mermaid 통합을 통해 지원됩니다. 다이어그램은 사용 가능한 페이지 너비로 제한되며 독립적으로 처리됩니다.

다이어그램 하나가 잘못된 경우, 변환기는 소스가 포함된 대체 콘텐츠를 삽입하고 나머지 섹션을 계속 렌더링합니다.

PlantUML, Graphviz, D2, WaveDrom, BPMN, Nomnoml 및 전체 TikZ는 현재 지원되지 않으며 이 페이지에 표시되어서는 안 됩니다.

변환기는 공개 HTTP 및 HTTPS 이미지뿐만 아니라 PNG, GIF, JPEG, WebP, SVG 형식의 유효한 base64 데이터 이미지를 지원합니다.

이미지는 페이지에 맞춰 크기가 조정되며 가로세로 비율이 유지됩니다. 그림, 캡션, 대체 텍스트(alt text), 제목, 안전한 크기 및 정렬을 유지할 수 있습니다.

그러나 많은 리포지토리 README는 다음과 같은 상대 경로를 사용합니다:

./images/screenshot.png
docs/architecture.svg
../assets/demo.gif

현재 업로드 워크플로우는 리포지토리 폴더를 패키징하거나 이러한 상대 경로 자산을 자동으로 분석하지 않습니다. PDF를 생성하기 전에 공개 이미지 URL 또는 지원되는 base64 데이터 이미지로 변환하십시오.

배지는 일반적으로 공개 이미지 URL을 사용하므로 이미지 호스트가 공개적으로 액세스 가능한 경우 렌더링될 수 있습니다. 배지나 이미지를 로드할 수 없는 경우 SolConverter는 로컬 자리 표시자를 삽입하고 변환을 계속합니다.

README 내부의 Markdown 링크는 절대 경로, 리포지토리 상대 경로 또는 페이지 조각(fragment) 링크일 수 있습니다.

절대 HTTP 및 HTTPS 링크는 리포지토리 외부에서도 유효합니다. ./docs/setup.md 또는 ../CONTRIBUTING.md와 같은 상대 경로 링크는 README가 독립 실행형 PDF가 된 후 유효한 대상으로 연결되지 않을 수 있습니다.

PDF를 공유하기 전에:

• 중요한 상대 경로 링크를 공개 절대 URL로 교체;
• 링크된 파일에만 의존하는 대신 중요한 지침을 직접 작성;
• 렌더링 후 제목 링크 검증;
• 리포지토리 내비게이션 없이도 문서가 이해되는지 확인;
• PDF를 보관용으로 사용할 경우 버전 또는 릴리스 정보 포함.

GitHub README 또한 Markdown 파일이지만, GitHub는 업로드된 파일 자체에 포함되지 않은 리포지토리 컨텍스트를 추가할 수 있습니다.

PDF는 표, 작업 목록, 펜스 코드, 자동 링크 및 제목과 같이 지원되는 GFM 구조를 보존할 수 있습니다. 또한 지원되는 MathJax 식 및 Mermaid 다이어그램을 렌더링할 수 있습니다.

변환기는 모든 GitHub 인터페이스 요소를 재현하지는 않습니다. 리포지토리 탭, 이슈 수, 릴리스 위젯, 브랜치 선택기, 동적으로 생성된 카드 및 기타 GitHub 페이지 테두리 장식(chrome)은 Markdown 소스의 일부가 아닙니다.

가장 깔끔한 독립 실행형 PDF를 위해 README 자체 문서에 프로젝트의 ID, 버전 컨텍스트 및 중요한 링크가 포함되어 있는지 확인하십시오.

README PDF는 독자에게 다음과 같은 정보가 필요할 때 간결한 기술 전달 문서 역할을 할 수 있습니다:

• 프로젝트 개요;
• 설치 및 설정 단계;
• 명령어 예시;
• 설정 요구 사항;
• 아키텍처 다이어그램;
• API 예시;
• 운영 참고 사항;
• 문제 해결 지침;
• 기여 또는 지원 상세 정보.

규모가 큰 문서 집합의 경우 모든 가이드를 한 파일에 억지로 넣기보다 README를 시작 문서로 다루십시오. 매우 긴 README에서 생성된 PDF도 유용할 수 있지만, 유지 관리 및 내비게이션을 위해 문서를 분리하는 것이 더 쉬울 수 있습니다.

리포지토리는 시간이 지남에 따라 변경됩니다. README를 PDF로 변환하면 릴리스, 제공물, 검토 또는 마일스톤과 관련된 읽기 쉬운 스냅샷이 생성됩니다.

보관하기 전에:

1. 프로젝트 또는 패키지 버전 추가;
2. 관련 날짜 또는 릴리스 식별자 포함;
3. 명령 및 설정 예시 검증;
4. 임시 링크 교체;
5. 이미지, 다이어그램 및 수식 검토;
6. 최종 PDF 생성 및 검사;
7. 릴리스 레코드 옆에 PDF 저장.

생성된 PDF는 스냅샷일 뿐 소스 제어되는 README를 대체하지 않습니다.

README 파일에는 원시 HTML, 원격 이미지 URL 및 잘못 구성된 블록이 포함될 수 있습니다.

SolConverter는 렌더링된 HTML을 새니타이즈하고, 스크립트 및 이벤트 처리기를 제거하고, 안전하지 않은 URL을 거부하고, 원시 HTML을 허용 목록으로 제한하고, 표 스팬을 제한하고, 제한적인 콘텐츠 보안 정책을 적용하며, 허용된 이미지 정책을 벗어나는 브라우저 요청을 차단합니다.

로컬 파일, localhost 대상, 사설 IP 리터럴, javascript: URL 및 지원되지 않는 리소스 스키마는 차단됩니다. 잘못된 이미지, 수식 및 다이어그램은 나머지 README가 계속 렌더링될 수 있도록 가능한 한 로컬에서 처리됩니다.

SolConverter는 README 파일에 일관된 문서 레이아웃을 적용합니다.

현재 웹 양식은 다음을 사용합니다:

• A4 페이지 크기;
• 세로 방향;
• 가독성 높은 출력을 위한 여백 관리;
• 현재 페이지 / 총 페이지 수 페이지 번호 매기기;
• README 파일 이름을 기반으로 한 출력 제목;
• 인쇄된 배경.

세로 레이아웃은 일반적인 독서를 위해 설계되었습니다. 다운로드하기 전에 항상 넓은 표와 코드를 미리 확인하십시오.

소스가 프로젝트 README이고 코드 펜스, GFM 구조, 배지, 리포지토리 상대 경로 이미지 및 리포지토리 링크에 대한 안내가 필요한 경우 이 README 전용 페이지를 사용하십시오.

보고서, 수학 문서, 기술 메모, 제안서, 다국어 문서 및 일반적인 .md 파일의 경우 메인 Markdown PDF 변환기를 사용하십시오.

두 페이지 모두 동일한 코어 변환 기능을 사용하지만 서로 다른 사용자 작업에 부합하고 다른 준비 지침을 제공합니다.

• 임의의 Markdown 파일을 PDF로 변환
• PDF를 Markdown으로 변환
• HTML을 Markdown으로 변환
• Word를 Markdown으로 변환
• 모든 파일에서 Markdown으로의 변환 도구 찾기