번역 / 교정

테마

Jekyll 의 테마 시스템은 확장성이 뛰어나서 공개 프로젝트 템플릿과 스타일을 활용하여 사이트의 외관을 꾸밀 수 있습니다. Jekyll 테마는 몇 가지 플러그인과 레이아웃, 조각파일, 스타일시트, 기타 자원들을 하나로 묶은 일종의 패키지이며, 그 안에 사이트의 컨텐츠를 집어넣을 수 있습니다.

테마 정하기

테마를 검색하고 미리보기 해볼 수 있는 갤러리가 여럿 있습니다:

루비 젬 기반 테마 이해하기

당신이 새 Jekyll 사이트를 생성하면 (jekyll new <PATH> 명령 사용), Jekyll 은 Minima 라고 하는 루비 젬 기반 테마가 적용된 사이트를 생성합니다.

루비 젬 기반 테마로, 사이트의 몇몇 (assets, _layouts, _includes, _sass 와 같은) 디렉토리들은 테마 젬 안에 저장되어 있어, 실제로 볼 수 없습니다. 그래도 Jekyll 은 빌드작업에 필요한 모든 디렉토리를 읽고 처리합니다.

Minima 의 경우, 당신의 Jekyll 사이트 디렉토리에서 볼 수 있는 파일은 다음과 같습니다:

.
├── Gemfile
├── Gemfile.lock
├── _config.yml
├── _posts
│   └── 2016-12-04-welcome-to-jekyll.markdown
├── about.markdown
└── index.markdown

Gemfile 과 Gemfile.lock 은 Bundler 관련 파일로서, 당신의 Jekyll 사이트를 빌드하기 위해 필요한 루비 젬과 그 버전을 기록하는데 사용합니다.

루비 젬 기반 테마는 개발자가 해당 테마 사용자들에게 쉽게 업데이트를 제공할 수 있게 해줍니다.

테마 젬을 사용중인 경우, 당신은 (원한다면) bundle update 를 실행해서 당신의 프로젝트에 있는 모든 젬을 업데이트할 수 있습니다. 또는 bundle update <THEME> 로, 예를 들어 minima 처럼 <THEME> 에 테마 이름을 넣어서, 특정 테마 젬만 업데이트할 수 있습니다.

루비 젬 기반 테마의 목적은 지속적으로 업데이트되는 강력한 테마의 장점을 모두 제공하는 것과 동시에, 테마의 여러 파일들로 인해 필요 이상으로 복잡해지는 것을 방지하여 당신이 해야하는 일에 집중할 수 있게 하는 것입니다: 컨텐츠 작성말이죠.

테마 기본값 덮어쓰기

Jekyll 테마에는 레이아웃과 조각파일, 스타일시트의 기본값이 설정되어 있습니다. 그러나, 당신이 작성한 내용으로 테마의 어떤 기본값이든 덮어쓸 수 있습니다.

사용중인 테마의 레이아웃이나 조각파일을 변경하려면, _layouts 이나 _includes 디렉토리를 복사하여 그 안의 원하는 파일을 수정하거나, 완전히 파일을 새로 만들어 덮어쓰려는 파일의 이름과 동일하게 저장하면 됩니다.

예를 들어, 사용하는 테마에 page 라는 레이아웃이 있을 경우, _layouts 디렉토리에 page 레이아웃 (다시 말해, _layouts/page.html) 을 생성 하여 테마의 레이아웃을 덮어쓸 수 있습니다.

자신의 컴퓨터에서 테마파일의 위치를 찾으려면:

  1. 테마의 젬 이름과 함께 bundle info --path 를 실행합니다. 예, Jekyll 기본 테마의 경우 bundle info --path minima.

    이 명령은 루비 젬 기반 테마 파일의 위치를 보여줍니다. 예를 들어, 맥OS 에서 Minima 테마 파일의 위치는 /usr/local/lib/ruby/gems/2.6.0/gems/minima-2.5.1 입니다.

  2. Finder 나 탐색기로 테마 디렉토리를 엽니다:

    # 맥OS 인 경우
open $(bundle info --path minima)

# 윈도우즈인 경우
# 먼저 젬의 설치 경로를 확인한다:
#
#   bundle info --path minima
#   => C:/Ruby26-x64/lib/ruby/gems/2.6.3/gems/minima-2.5.1
#
# 그 다음 `/` 를 `\` 로 바꿔서 위의 경로를 탐색기로 연다
explorer C:\Ruby26-x64\lib\ruby\gems\2.6.3\gems\minima-2.5.1

# 리눅스인 경우
xdg-open $(bundle info --path minima)

    Finder 나 익스플로러 창이 열려 테마의 파일과 디렉토리를 보여줍니다. Minima 테마 젬에는 다음 파일들이 포함되어 있습니다:

    .
├── LICENSE.txt
├── README.md
├── _includes
│   ├── disqus_comments.html
│   ├── footer.html
│   ├── google-analytics.html
│   ├── head.html
│   ├── header.html
│   ├── icon-github.html
│   ├── icon-github.svg
│   ├── icon-twitter.html
│   └── icon-twitter.svg
├── _layouts
│   ├── default.html
│   ├── home.html
│   ├── page.html
│   └── post.html
├── _sass
│   ├── minima
│   │   ├── _base.scss
│   │   ├── _layout.scss
│   │   └── _syntax-highlighting.scss
│   └── minima.scss
└── assets
    └── main.scss

테마 파일에 대하여 완전히 이해했다면, 어떤 테마 파일이든지 당신의 Jekyll 사이트 디렉토리 안에 비슷한 이름으로 파일을 생성하여 덮어쓸 수 있습니다.

또 다른 예로, Minima 의 푸터를 덮어쓰는 경우를 생각해 봅시다. Jekyll 사이트에, _includes 폴더를 만들고 그 안에 footer.html 이라는 파일을 저장합니다. 이제부터 Jekyll 은 Minima 테마 젬의 footer.html 대신 사이트에 들어있는 footer.html 파일을 사용할 것 입니다.

스타일시트를 수정하려는 경우에는 추가로 필요한 작업이 있는데, 메인 SASS 파일 (Minima 테마에서는 _sass/minima.scss) 을 Site Source 의 _sass 로 복사해야 합니다.

Jekyll 은 아래 폴더에 있는 테마의 기본 파일들을 확인하기 전에 사이트의 컨텐츠를 먼저 확인합니다:

  • /assets
  • /_layouts
  • /_includes
  • /_sass

테마 파일의 복사본을 만든 경우 해당 파일에 대해서는 테마의 업데이트가 적용되지 않는다는 것을 기억하세요. 이에 관한 대안으로, 스타일시트에 관련된 테마 업데이트는 유지하고자 한다면, 직접 만든 CSS 파일을 고유한 이름으로 추가하고, 명시도가 높은 CSS 셀렉터를 사용하세요.

사용중인 테마의 설명서나 소스 저장소를 참고하여 덮어쓸 수 있는 파일에 관한 더 많은 정보를 얻을 수 있습니다.

루비 젬 기반 테마를 일반 테마로 변환하기

루비 젬 기반 테마를 없애고, 모든 파일이 테마의 젬 내부가 아닌, 당신의 Jekyll 사이트 디렉토리에 있는 일반 테마로 변환하려 한다고 가정해봅시다.

그러기 위해서는, 테마 젬 디렉토리 안에 있는 모든 파일을 당신의 Jekyll 사이트 디렉토리에 복사하세요. (예, 당신의 Jekyll 사이트가 /myblog 에 있다면 모든 파일을 이 /myblog 에 복사합니다. 자세한 내용은 이전 섹션을 참고하세요.)

그 다음 테마가 참조하고 있던 플러그인들을 Jekyll 에 알려주어야 합니다. 이 플러그인들은 테마 gemspec 파일의 런타임 종속성 (Runtime Dependency) 을 보면 알 수 있습니다. Minima 테마로부터 변환하는 상황을 예로 들어보면, 다음과 같은 내용이 있을 것입니다:

spec.add_runtime_dependency "jekyll-feed", "~> 0.12"
spec.add_runtime_dependency "jekyll-seo-tag", "~> 2.6"

이 참조 내용을 Gemfile 에 추가해야 하는데, 두 가지 방법이 있습니다.

이것들을 개별적으로 Gemfile 과 _config.yml 모두에 나열합니다.

# ./Gemfile

gem "jekyll-feed", "~> 0.12"
gem "jekyll-seo-tag", "~> 2.6"

# ./_config.yml

plugins:
  - jekyll-feed
  - jekyll-seo-tag

아니면 _config.yml 은 수정하지 않고, Gemfile 에 Jekyll 플러그인으로서 명시적으로 나열합니다. 이렇게요:

# ./Gemfile

group :jekyll_plugins do
  gem "jekyll-feed", "~> 0.12"
  gem "jekyll-seo-tag", "~> 2.6"
end

어떤 방법이든지, bundle update 하는 것을 잊지 마세요.

GitHub Pages 는 Bundler 로 플러그인을 불러오지 않기 때문에 GitHub Pages 에 게시하는 경우에는 오직 _config.yml 만 수정해야 합니다.

마지막으로, 환경설정 파일과 Gemfile 에서 테마 젬에 대한 참조를 제거합니다. 예를 들어, minima 를 제거하려면:

  • Gemfile 을 열고 gem "minima", "~> 2.5" 를 제거합니다.
  • _config.yml 을 열고 theme: minima 를 제거합니다.

이제 bundle update 명령은 테마 젬에 대한 업데이트를 수행하지 않습니다.

루비 젬 기반 테마 설치하기

루비 젬 기반 테마를 사용하는 Jekyll 사이트를 만드는 방법은 jekyll new <PATH> 말고도 또 있습니다. 온라인 상에서 찾은 루비 젬 기반 테마를 당신의 Jekyll 프로젝트에 적용할 수 있습니다.

예를 들어, jekyll theme on RubyGems 라고 검색하여 다른 루비 젬 기반 테마들을 찾을 수 있습니다. (이름에 jekyll-theme 을 포함하는 관례를 따르지 않는 테마도 있다는 것을 알아두세요.)

루비 젬 기반 테마를 설치하려면:

  1. 사이트의 Gemfile 에 테마 젬을 추가합니다:

    # ./Gemfile

# 이것은 하나의 예제로, 자신이 원하는 테마 젬을 여기에 선언한다.
gem "jekyll-theme-minimal"

    처음에 jekyll new 명령으로 시작한 경우에는, gem "minima", "~> 2.0" 부분을 원하는 젬으로 변경합니다:

    # ./Gemfile

- gem "minima", "~> 2.5"
+ gem "jekyll-theme-minimal"

  2. 테마를 설치합니다:

    bundle install

  3. 다음 내용을 사이트의 _config.yml 에 추가하여 테마를 활성화합니다:

    theme: jekyll-theme-minimal

  4. 사이트를 빌드합니다:

    bundle exec jekyll serve

여러 개의 테마를 Gemfile 에 나열할 수 있지만, _config.yml 파일에서 선택할 수 있는 테마는 오직 하나뿐입니다.

당신의 사이트를 GitHub Pages 에 게시하는 경우, GitHub Pages 는 일부 젬 기반 테마들만 지원한다는 것을 기억하세요. GitHub Pages 는 환경설정 remote-themes 사용으로 GitHub 에서 호스팅하는 모든 테마들도 마치 젬 기반 테마인 것 처럼 지원합니다.

루비 젬 기반 테마 만들기

당신이 만약 (단순히 테마를 사용하는 것이 아닌) Jekyll 테마 개발자라면, 자신의 테마를 RubyGems 로 패키지화 하여 다른 사용자들이 Bundler 로 설치할 수 있게 만들 수 있습니다.

루비 젬을 만드는 것에 익숙하지 않더라도, 걱정하지 마세요. Jekyll 의 new-theme 명령이 새 테마의 뼈대를 만드는 것을 도와줄 것입니다. jekyll new-theme 명령에 테마 이름을 인수로 전달해 실행하세요.

여기 예제가 하나 있습니다:

jekyll new-theme jekyll-theme-awesome
    create /path/to/jekyll-theme-awesome/_layouts
    create /path/to/jekyll-theme-awesome/_includes
    create /path/to/jekyll-theme-awesome/_sass
    create /path/to/jekyll-theme-awesome/_layouts/page.html
    create /path/to/jekyll-theme-awesome/_layouts/post.html
    create /path/to/jekyll-theme-awesome/_layouts/default.html
    create /path/to/jekyll-theme-awesome/Gemfile
    create /path/to/jekyll-theme-awesome/jekyll-theme-awesome.gemspec
    create /path/to/jekyll-theme-awesome/README.md
    create /path/to/jekyll-theme-awesome/LICENSE.txt
    initialize /path/to/jekyll-theme-awesome/.git
    create /path/to/jekyll-theme-awesome/.gitignore
Your new Jekyll theme, jekyll-theme-awesome, is ready for you in /path/to/jekyll-theme-awesome!
For help getting started, read /path/to/jekyll-theme-awesome/README.md.

관련된 폴더에 당신의 템플릿 파일을 추가하세요. 그 다음 .gemspec 과 README 파일을 작성하세요.

레이아웃과 조각파일

테마의 레이아웃과 조각파일은 사이트에 있는 것과 동일한 방식으로 동작합니다. 레이아웃은 테마의 /_layouts 폴더에, 조각파일은 테마의 /_includes 폴더에 저장하세요.

예를 들어, 당신의 테마에 /_layouts/page.html 파일이 있고, 머리말에 layout: page 가 적힌 페이지가 있다면, Jekyll 은 먼저 사이트의 _layouts 폴더에서 page 레이아웃을 찾아보고, 만약 없다면, 테마에 들어있는 page 레이아웃을 사용할 것입니다.

자원

동일한 상대경로를 가진 파일이 없다면 /assets 에 있는 모든 파일은 빌드 시 사용자의 사이트에 복사될 것입니다. 여기에 보관할 수 있는 자원의 종류는 제한이 없습니다: SCSS, 이미지, 웹 폰트, 등등. 이 파일들은 Jekyll 의 페이지나 정적 파일과 동일하게 동작합니다:

  • 파일의 첫 부분에 머리말이 있다면, 렌더링 과정을 거칩니다.
  • 파일에 머리말이 없다면, Site Destination 으로 단순 복사됩니다.

이 덕분에 테마 제작자는 기본 /assets/styles.scss 파일을 제공할 수 있어 레이아웃들에 /assets/styles.css 를 적용할 수 있습니다.

당신이 알고 있는 Jekyll 의 사용방식과 동일하게, /assets 안의 모든 파일은 생성된 사이트의 /assets 폴더에 출력될 것입니다.

스타일시트

반복되는 이야기지만, 당신이 알고 있는 Jekyll 의 사용방식과 동일하게, 테마의 스타일시트는 테마의 _sass 폴더에 저장해야 합니다.

_sass
└── jekyll-theme-awesome.scss

사용자의 스타일시트에 @import 지시어를 사용해서 테마에 들어있는 스타일을 포함시킬 수 있습니다.

@import "{{ site.theme }}";

테마 젬 종속성3.5.0

사이트 환경설정 파일의 plugins 배열에 명시되지 않은 경우에도 화이트리스트된 모든 runtime_dependencies 는 자동적으로 Jekyll 이 사용하려 할 것입니다. (메모: 화이트리스트는 --safe 옵션과 함께 빌드 혹은 미리보기하는 경우에만 필요합니다.)

이것으로, 최종 사용자는 자신이 사용하는 테마 젬을 올바르게 작동시키기 위해 필요한 플러그인들을 찾아 환경설정 파일에 넣을 필요가 없습니다.

테마-젬 사전-환경설정4.0

Jekyll 은 테마-젬의 루트 디렉토리에서 _config.yml 을 읽어들여 사이트의 기존 환경설정 데이터에 병합시킬것 입니다.

하지만 테마로부터 불러오는 다른 엔티티들과는 다르게, 환경설정 파일을 읽어들이는 것은 몇 가지 제약을 가지고 있습니다. 요약하면 다음과 같습니다:

  • Jekyll 의 디폴트 설정들은 테마-환경설정으로 덮어쓰여지지 않습니다. 주도권은 여전히 사용자측에 있습니다.
  • 테마-환경설정-파일은 심볼릭 링크일 수 없습니다. 혹여 safe mode 이거나 심볼링 링크가 테마-젬 안에 있는 일반 파일을 가리키는 경우에도 불가능합니다.
  • 테마-환경설정은 키-값 쌍들의 묶음이어야 합니다. 비어있는 환경설정 파일이나 단순히 키 아래에 항목을 나열하는 환경설정 파일, 단지 문자열이 들어있는 환경설정 파일등은 아무런 경고도 없이 조용히 무시됩니다.
  • 테마-환경설정에서 정의된 모든 설정은 사용자가 덮어쓸 수 있습니다.

While this feature is to enable easier adoption of a theme, the restrictions ensure that a theme-config cannot affect the build in a concerning manner. Any plugins required by the theme will have to be listed manually by the user or provided by the theme’s gemspec file.

This feature will let the theme-gem to work with theme-specific config variables out-of-the-box.

테마 관련 문서 작성

테마 안에는 사이트 작성자에게 테마를 설치하고 사용하는 방법을 설명하는 /README.md 파일이 있어야 합니다. 테마에 포함된 레이아웃과 조각파일은 어떠한지? 사이트 환경설정 파일에 특별히 추가해야할 사항이 있는지?

스크린샷 추가하기

테마는 시각적입니다. 소스코드 저장소로부터 프로그램적으로 가져올 수 있는 경로인 /screenshot.png 에 스크린샷을 넣어두어 사용자들에게 테마가 어떻게 생겼는지 볼 수 있게 해주세요. 테마의 문서에도 스크린샷을 포함시킬 수 있습니다.

테마 미리보기

테마를 미리보기 하려면 실제로 사용해보세요. 임의의 가상 컨텐츠, 예를 들면 /index.html 과 /page.html 같은 파일을 넣어두는게 도움이 될 것입니다. 이로써 Jekyll 사이트의 미리보기를 하는 것과 동일하게, jekyll build 와 jekyll serve 명령으로 테마를 미리보기 할 수 있습니다.

로컬상에서 테마를 미리보기하는 경우, 컴파일된 사이트가 배포판에 포함되지 않도록 테마의 .gitignore 파일에 /_site 를 추가하는 것을 잊지 마세요.

테마 배포하기

테마는 RubyGems.org 를 통해 배포됩니다. RubyGems 계정이 필요한데, 무료로 생성할 수 있습니다.

  1. 먼저, 모든 파일을 git 저장소에 넣어야합니다:

    git init # Only the first time
git add -A
git commit -m "Init commit"

  2. 다음, 아래의 명령을 사용해서 테마를 패키지로 만드는데, jekyll-theme-awesome 부분을 당신의 테마 이름으로 바꾸세요:

    gem build jekyll-theme-awesome.gemspec

  3. 마지막으로, 아래의 명령을 사용해서 패키지로 만든 테마를 RubyGems 서비스에 등록하는데, 이때 역시 jekyll-theme-awesome 부분을 당신의 테마 이름으로 바꾸세요:

    gem push jekyll-theme-awesome-*.gem

  4. 테마의 새 버전을 배포할 때에는, gemspec 파일 (이 예제에서는 jekyll-theme-awesome.gemspec) 에 버전정보를 업데이트하고, 위의 1 - 3 단계를 다시 수행합니다. 테마의 버전정보를 변경할 때는 유의적 버전 명세를 따르기를 권장합니다.