로컬 환경 만들기

GitHub Docs 응용 프로그램을 컴퓨터에서 로컬로 실행할 수 있습니다.

이 문서의 내용

GitHub Docs 사이트 구조 정보

GitHub Docs 사이트는 원래 Ruby on Rails 웹 응용 프로그램이었습니다. 얼마 후 이 웹 응용 프로그램은 Jekyll에서 제공하는 정적 사이트로 변환되었습니다. 그리고 몇 년 후 다른 Ruby 정적 사이트 생성기인 Nanoc로 마이그레이션되었습니다.

현재는 미들웨어를 사용하여 적절한 HTTP 리디렉션, 언어 헤더 감지, 동적 콘텐츠 생성을 지원하는 Express 기반의 동적 Node.js 웹 서버로, GitHub의 제품 문서(예: Free, Pro, & Team 및 GitHub Enterprise Server) 등 다양한 버전의 제품 문서를 지원하고 있습니다.

이 사이트의 도구는 수년에 걸쳐 변경되었지만 원래 Jekyll 사이트에서 검증된 제작 규칙이 많이 유지되었습니다.

  • 콘텐츠는 content 디렉터리에 Markdown 파일로 작성됩니다.
  • data 디렉터리의 파일은 {% data %} 태그를 통해 템플릿에 사용할 수 있습니다.
  • Markdown 파일에는 프런트 매터가 포함될 수 있습니다.
  • redirect_from Jekyll 플러그 인 동작이 지원됩니다.

로컬 환경 설정

몇 가지 초기 설정 후 GitHub Docs 리포지토리를 복제하고 컴퓨터에서 로컬로 애플리케이션을 실행할 수 있습니다.

Node.js 설치

GitHub Docs 사이트는 Node.js를 기반으로 합니다. macOS, Windows 및 Linux 환경에서 실행됩니다.

사이트를 실행하려면 Node.js가 필요합니다. Node.js를 설치하려면 nodejs.org에서 "LTS" 설치 관리자를 다운로드합니다. GitHub Docs 리포지토리의 package.json 파일에서 필요한 노드 버전을 확인할 수 있습니다. 노드 버전은 노드 주 버전 16 또는 노드 주 버전 18을 사용할 수 있음을 나타내는 다음 예시와 유사하게 engine 필드에 나열됩니다.

"engines": {
    "node": "^16 || ^18"
}

nodenv를 사용하는 경우 Node.js 버전 전환에 대한 지침은 nodenv 문서를 참조하세요.

로컬 GitHub Docs 서버 시작

인기 npm 패키지 관리자가 포함된 Node.js를 설치한 후 터미널을 열고 다음 명령을 실행합니다.

git clone https://github.com/github/docs
cd docs
npm ci
npm start

이제 서버가 실행 중이어야 합니다. 로컬 미리 보기 환경에 액세스하려면 브라우저에서 localhost:4000을 방문합니다.

로컬 서버를 중지할 준비가 되면 터미널 창에 Ctrl+C를 입력합니다.

참고: 일반적으로 최신 버전의 분기를 풀할 때에만 npm ci 및 npm run build를 실행하면 됩니다.

  • npm ci는 package-lock.json 파일을 업데이트하지 않고 종속 구성 요소를 새로 설치합니다.
  • npm run build는 JavaScript, CSS 파일 등의 정적 자산을 생성합니다.

GitHub Docs 응용 프로그램의 디버깅 및 문제 해결에 대해 자세히 알아보려면 github/docs 리포지토리에서 "환경 문제 해결" 항목을 참조하세요.

브라우저 바로 가기 사용

GitHub Docs 리포지토리의 src/bookmarklets 디렉터리에는 GitHub 설명서를 검토하는 데 도움이 되는 브라우저 바로 가기가 포함되어 있습니다. 자세한 내용은 디렉터리의 README를 참조하세요.

다른 언어 사용

기본적으로 로컬 서버는 지원되는 모든 언어가 활성화된 상태로 실행되지 않습니다. 특정 언어로 로컬 서버를 실행해야 하는 경우 임시로 start의 package.json 스크립트를 편집하고 ENABLED_LANGUAGES 변수를 업데이트할 수 있습니다.

예를 들어 영어 외에 일본어와 포르투갈어도 사용하도록 설정하려는 경우 start 스크립트에서 package.json을 편집하고 ENABLED_LANGUAGES='en,ja,pt'를 설정할 수 있습니다. 그런 다음 변경 내용이 적용되도록 서버를 다시 시작합니다.

참고: 변경 내용을 커밋하기 전에 package.json 파일을 원래 상태로 되돌려야 합니다.

지원되는 언어 코드는 src/languages/lib/languages.js에 정의되어 있습니다.

GitHub Codespaces 사용하기

GitHub Docs을(를) 로컬로 실행하는 대신 GitHub Codespaces을(를) 사용할 수 있습니다. GitHub Codespaces을(를) 사용하면 브라우저에서 직접 변경 내용을 편집하고 미리 보고 테스트할 수 있습니다.

codespace를 작업에 사용하는 방법에 대한 자세한 내용은 GitHub 설명서에서 "codespace에서 GitHub Docs 작업" 항목을 참조하세요.

추가 참고 자료