GitHub Pages
GitHub Pages 는 개인이나 단체 또는 저장소를 위한 공개
웹 페이지로서, GitHub 이 제공하는 github.io 도메인이나 자신만의 도메인에
자유롭게 호스팅할 수 있습니다. GitHub Pages 는 내부적으로 Jekyll 에 의해
작동되고 있기 때문에, Jekyll 기반의 웹사이트를 무료로 호스팅하기에 탁월한 방법입니다.
당신이 소스파일을 push 하면 GitHub Pages 에 의해 자동으로 사이트가 생성됩니다. GitHub Pages 는 일반 HTML 문서에 대해서도 동일하세 잘 작동한다는 것을 알아두시기 바랍니다. 왜냐하면 Jekyll 은 단순히 머리말이 없는 파일을 정적 자원으로 처리하기 때문입니다. 따라서 HTML 파일만 push 하는 경우에는, 다른 추가작업이 필요하지 않습니다.
전에 한 번도 GitHub Pages 로 웹사이트를 생성해본 적이 없다구요? Jonathan McGlone 이 작성한 이 놀라운 설명서를 참고해 시작해보길 바랍니다. 당신이 GitHub Pages 에 웹사이트를 만들기 위해 알아두어야 할 Git, GitHub, Jekyll 에 관한 설명이 이 설명서에 담겨있습니다.
github-pages 루비 젬
GitHub 에 있는 우리 친구들이 제공해 준 루비 젬 github-pages 로 GitHub Pages 에서 사용하는 Jekyll 과 그 의존요소들을 관리할 수 있습니다. GitHub Pages 에 사이트를 게시할 때, 예상치 못하게 여러 루비 젬들에 대한 버전 불일치 문제를 마주칠수도 있는데, 당신의 프로젝트에 이 루비 젬을 사용해서 이러한 문제들을 피할 수 있습니다.
GitHub Pages 는 safe 모드로 작동하며 오직 허용 목록에 포함된
플러그인만 사용할 수 있습니다.
현재 당신의 프로젝트에 적용된 것과 동일한 버전의 루비 젬을 사용하려면,
Gemfile 에 아래 내용을 추가하세요:
source "https://rubygems.org"
gem "github-pages", group: :jekyll_plugins
자주 bundle update 를 실행하세요.
GitHub Pages 설명서와 도움말, 지원
문제해결 설명서를 포함해, 당신이 GitHub Pages 로 할 수 있는 일에 대한 더 많은 정보는 GitHub Pages 도움말을 확인해보세요. 그래도 해결되지 않는다면, GitHub 지원에 문의하세요.
프로젝트 페이지 URL 구조
때론 GitHub 의 gh-pages 브랜치에 push 하기 전에 당신의 Jekyll 사이트를
미리보기해보는 것이 좋을 때가 있습니다. GitHub 이 프로젝트 페이지에
사용하는 하위 디렉토리 형식의 URL 구조가 문제가 될 수 있습니다. URL
필터가 이것을 확인하는데에 유용합니다.
<!-- For styles with static names... -->
<link href="{{ "/assets/css/style.css" | relative_url }}" rel="stylesheet">
<!-- For documents/pages whose URLs can change... -->
[{{ page.title }}]("{{ page.url | relative_url }}")
이로써 당신의 사이트는 로컬에서 미리보기할 때에는 최상위 디렉토리에서
작동하지만, GitHub 에 의해 gh-pages 브랜치에서 생성되었을 때에는 모든 URL 이
올바르게 생성될 것입니다.
GitHub Pages 에서 Jekyll 사용하기
GitHub Pages 는 GitHub 에 있는 저장소들의 특정 브랜치를 검색하여 작동합니다. 지원하는 방식은 두 가지: 사용자/단체 페이지와 프로젝트 페이지가 있습니다. 이 두 가지 사이트 게시 방법은 아주 조그만 차이점 몇 가지를 제외하고는 거의 동일합니다.
사용자 페이지와 단체 페이지
사용자 페이지와 단체 페이지는 오로지 GitHub Pages 에 관련된 파일만을 위한 특별한
GitHub 저장소를 필요로 합니다. 저장소의 이름은 반드시 계정명으로 시작해야
합니다. 예를 들어, @mojombo 의 사용자 페이지 저장소의 이름은
mojombo.github.io 입니다.
저장소의 master 브랜치를 가지고 GitHub Pages 사이트를 구성하고 게시하기
때문에, 반드시 해당 브랜치에 Jekyll 사이트 컨텐츠를 저장하세요.
커스텀 도메인은 저장소 이름에 영향을 미치지 않습니다
GitHub Pages 는 최초에 username.github.io 서브 도메인에서
제공됩니다. 따라서 저장소의 이름은 커스텀 도메인이
사용되더라도 이 방식을 따라야 합니다.
프로젝트 페이지
사용자/단체 페이지와는 다르게, 프로젝트 페이지는 해당 프로젝트의 실제 저장소에
함께 보관하는데, 단, gh-pages 라는 특별한 이름의 브랜치나 master 브랜치의
docs 폴더에 저장한다는 차이점이 있습니다. Jekyll 에 의해 컨텐츠가 렌더링된 후,
username.github.io/project (커스텀 도메인을 사용하지 않았을 때 기준)
와 같이 사용자 페이지 서브 도메인의 하위 경로에 결과물이 만들어집니다.
Jekyll 프로젝트의 저장소 자체가 이러한 브랜치 구조에 대한 완벽한 예시입니다—마스터 브랜치에는 실제 Jekyll 소프트웨어 프로젝트가 담겨 있고, 바로 지금 보고있는 Jekyll 웹 사이트는 동일한 저장소의 docs 폴더에 들어 있습니다.
GitHub 의 공식 문서 중 사용자와 단체, 프로젝트 페이지에서 더 자세한 예시를 확인할 수 있습니다.
소스 파일은 반드시 루트 디렉토리에 있어야 합니다
GitHub Pages 는 “Site Source” 환경설정을 덮어쓰기 때문에, 루트 디렉토리가 아닌 다른 디렉토리에 파일을 넣어두면 사이트가 올바르게 구성되지 않을 수 있습니다.
윈도우즈에 github-pages 루비 젬 설치하기
공식적으로 윈도우즈를 지원하지는 않지만, 윈도우즈에
루비 젬 github-pages 를 설치할 수 있습니다.
윈도우즈 관련문서 페이지에
그 방법이 설명되어 있습니다.