[GitHub] Jekyll 블로그 테마 설치하기 - Just The Docs

오랫만에 github repo 정리하다가 

Jekyll 테마 중 마음에 드는 테마를 발견해서

블로그용으로 세팅을 해보기로 하였습니다.

 

https://jekyllthemes.io/theme/just-the-docs

Just The Docs – Responsive documentation Jekyll theme – Jekyll Themes

 

이번에 선택한 Jekyll 테마는 바로 Just The Docs인데요.

 

가이드가 잘 되어 있어서 쉽게 따라할 수 있었습니다.

 

 

git clone

 

• 기존 repo를 fork 하는 경우 Pull Request 시 해당 repo로 할 수 있기 때문에 
• 'Just The Docs' repo를 clone 하지 않고 '본인의 git repo' 내 remote_theme로 세팅하려고 합니다.
• 우선 github에서 'username.github.io'로 repo 생성 후(ex. 100sang.github.io) 로컬 환경으로 clone 합니다.
  
  

$ git clone https://github.com/100sang/100sang.github.io github-blog

 

• clone한 로컬 폴더로 이동하여 (ex. github-blog)
• 해당 폴더 내 '_config.yml' 파일 생성 후 remote_theme를 아래와 같이 추가해줍니다.

$ cd github-blog
$ vi _config.yml        

remote_theme: just-the-docs/just-the-docs

 

 

theme configuration

 

• 'just-the-docs' 가이드를 참고하여 '_config.yml' 내 옵션을 추가합니다.
  (참고 : https://just-the-docs.github.io/just-the-docs/docs/configuration/)
  
  

* Demo 사이트 기준 추가할 영역입니다.

 

[_config.yml]

하나씩 확인하면서 세팅하기가 귀찮으신 분들은

아래 YAML 파일을 참고하여 세팅을 진행해주시면 됩니다.

https://github.com/just-the-docs/just-the-docs/blob/main/_config.yml

 

  1) Site settings : github 타이틀 및 URL 정의

 

# Site settings

title: Just the Docs  # 사이트 제목
description: A Jekyll theme for documentation # 사이트 설명
baseurl: "/" # 메인 접속경로 e.g. /blog, or / 
url: "https://username.github.io" # 본인 github 주소, e.g. http://example.com

 

   2) Aux links, Footer : 각 링크 영역 주소를 '본인 github url'로 수정

 

# Aux links for the upper right navigation
aux_links:  # 본인의 github url로 수정
  "Just the Docs on GitHub":
    - "//github.com/just-the-docs/just-the-docs"
    
    
# Footer "Edit this page on GitHub" link text
gh_edit_link: true # show or hide edit this page link
gh_edit_link_text: "Edit this page on GitHub"  
gh_edit_repository: "https://github.com/just-the-docs/just-the-docs"  # 본인의 github url로 수정

 

  3) Search : 검색 옵션이 필요한 경우 site search 옵션 추가

# Enable or disable the site search
# Supports true (default) or false
search_enabled: true

search:
  # Split pages into sections that can be searched individually
  # Supports 1 - 6, default: 2
  heading_level: 2
  # Maximum amount of previews per search result
  # Default: 3
  previews: 3
  # Maximum amount of words to display before a matched word in the preview
  # Default: 5
  preview_words_before: 5
  # Maximum amount of words to display after a matched word in the preview
  # Default: 10
  preview_words_after: 10
  # Set the search token separator
  # Default: /[\s\-/]+/
  # Example: enable support for hyphenated search words
  tokenizer_separator: /[\s/]+/
  # Display the relative url in search results
  # Supports true (default) or false
  rel_url: true
  # Enable or disable the search button that appears in the bottom right corner of every page
  # Supports true or false (default)
  button: false

 

  4) color_schme : 'just-the-docs' color 옵션 선택 

* 기본 : 'light' - 'dark' 테마 사용을 원할경우 옵션 수정 

# Color scheme currently only supports "dark", "light"/nil (default), or a custom scheme that you define
color_scheme: nil

 

 

[index.md]

 

_config.yml 파일 세팅이 완료되면 동일한 방법으로

'index.md'라는 Markdown 페이지를 하나 생성하여 default layout을 추가해줍니다. 

---
layout: default
title: Home
nav_order: 1
description: "description"
permalink: /
---

# Welcome to github.io
{: .fs-8 }

Github Description
{: .fs-6 .fw-300 }

[Get started now](#getting-started){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 } [View it on GitHub](https://github.com/just-the-docs/just-the-docs){: .btn .fs-5 .mb-4 .mb-md-0 }

---

## Getting started
... (생략) ...

 

git push

• 수정이 모두 완료 되었으면, 본인 github로파일을 push합니다.

$ git push

 

• github repo에 접속하여 정상적으로 파일이 commit 되었는지 확인합니다.

 

• repo 내 [Settings] > [Pages]에서 'GitHub Pages'가 main branch로 반영되었는지 확인합니다.

 

 

GitHub Pages

• 위에서 생성한 github.io url로 접속하여 'just-the-docs' 테마가 잘 적용되었는지 확인하면 끝 : )

 

• 'search 옵션' 추가 시 아래와 같이 markdown 페이지에 포함된 text가 검색되는 것을 확인할 수 있습니다.

 

• Dark 테마의 경우 아래와 같이 적용 됩니다.
• '_config.yml' 내 'color_scheme:dark' 옵션을 추가하셔서 적용하시면 됩니다.

 

 

Add Pages

• 'docs' 폴더 생성 후 Markdown 페이지를 추가해줍니다.

 

• 'layout, title, nav_order'로 navigation에 표시될 메뉴명 및 순서를 추가한 후 내용을 작성합니다.
  (https://just-the-docs.github.io/just-the-docs/docs/navigation-structure)

[menu2.md 예시]

---
layout: default
title: Menu2
nav_order: 2
---

# Menu2
{: .no_toc }

Menu2 Test
{: .fs-6 .fw-300 }

 

• 2depth 형태로 메뉴를 추가하고 싶은 경우, Parent 메뉴 내 'has_children: true' 옵션을 추가합니다.

[menu3.md 예시]

---
layout: default
title: Menu3
nav_order: 3
has_children: true
permalink: /docs/menu3
---

# Menu3

Menu3 Page tests

 

• Children 페이지 생성 후 'parent' 메뉴 타이틀과 'nav_order'로 sub menu 정보를 정의합니다.

[menu3-child.md 예시]

---
layout: default
title: Child1
parent: Menu3
nav_order: 1
---

# Child
{: .no_toc }

## Table of contents
{: .no_toc .text-delta }

 

• push가 완료되면 위에 추가한 Menu들이 잘 적용된 것을 확인할 수 있습니다.

 

Jeklly 블로그의 remote_theme 관련 방법이 많이 없어서

이번에 세팅하면서 작성해 보았습니다 ~

 

추가로 Jeklly github 블로그 생성 및 테마 관련 궁금하신 분들은 아래 링크를 참고해주세요 : )

 

**** 참고자료

• github 블로그 만들기 : https://pages.github.com
• jeklly 테마 (Just the Docs) : https://github.com/just-the-docs/just-the-docs
• Just the Docs (remote-theme) : https://github.com/pmarsceill/jtd-remote