0songha0

Git 블로그 카테고리 목록 페이징 기능 구현

★ 추후 다시 작성 예정입니다

현재 Git 블로그는 GitHub Pages를 통해 자동 빌드 및 배포가 되고 있습니다.
*.github.io 리포지토리에 push 시 GitHub가 Jekyll로 빌드해서 정적 웹사이트로 배포합니다.

GitHub Pages는 글 카테고리 목록 페이징 및 커스텀 플러그인을 지원하지 않습니다.
GitHub Actions로 jekyll-paginate-v2 플러그인을 사용하면 카테고리별 페이징이 가능합니다.

수동 페이징 구현은 반복 작업이 많고 번거로우므로 권장하지 않습니다.

GitHub Actions 페이징 플러그인 사용 원리
main 브랜치 push 시 .github/workflows/jekyll.yml 워크플로우가 실행되어,
bundle exec jekyll build로 생성된 _site 폴더가 gh-pages 브랜치에 push 됩니다.
gh-pages 브랜치를 배포하므로, 기본 빌드 환경에서 지원하지 않는 커스텀 플러그인도 동작 가능합니다.

jekyll-paginate-v2 플러그인 추가

Gemfile 파일 수정

source "https://rubygems.org"
gemspec

gem 'jekyll-admin', group: :jekyll_plugins
gem 'jekyll-sitemap'
gem 'jekyll-paginate-v2' // 추가

Gemfile 파일에 카테고리 목록 페이징을 위한 jekyll-paginate-v2 플러그인을 추가합니다.
GitHub Pages 기본 빌드에서는 동작하지 않으므로, GitHub Actions로 직접 빌드해야 합니다.

_config.yml 설정 수정

// 기존 jekyll-paginate 페이징 주석
# paginate: 5
# paginate_path: /page:num/

plugins:
  - jekyll-paginate-v2 // jekyll-paginate를 수정
  - jekyll-sitemap
  - jekyll-gist
  - jekyll-include-cache

// 전체 페이징 설정 추가
pagination:
  enabled: true
  per_page: 5
  sort_field: 'date'
  sort_reverse: true
  permalink: "/page/:num/"
  title: ""

// 카테고리 및 태그별 페이징 설정 추가
autopages:
  enabled: true
  categories:
    enabled: true
    title: '카테고리: :cat'
    permalink: '/categories/:cat/'
    layout: 'archive-taxonomy'

_config.yml 파일에서 jekyll-paginate-v2 플러그인을 활성화합니다.
/categories/카테고리명 페이지가 생기고, archive-taxonomy.html 레이아웃이 적용됩니다.

메인페이지 전체 목록 페이징

메인페이지 페이징 활성화

---
pagination:
  enabled: true

index.html 파일에 페이징 활성화 코드를 추가합니다.

메인페이지 페이징 코드 추가

home.html 파일 하단에 페이징 로직을 작성한 html을 추가합니다.

카테고리 목록 페이징

카테고리 페이징 활성화

pagination:
  enabled: true
  category: app-dev
  per_page: 5
  sort_reverse: true

_pages/categories/카테고리명.md 파일에 페이징 활성화 코드를 추가합니다.

GitHub Actions로 블로그 빌드

Ruby 설치

https://rubyinstaller.org/downloads
Ruby 공식 설치 페이지에서 Ruby+Devkit 3.x.x 버전 다운로드 후 설치합니다.

Ruby 설치 확인 명령어

ruby -v
gem -v

VS Code 터미널은 툴을 재시작해야 명령어를 사용할 수 있습니다.

Bundler 설치

gem install bundler

Ruby 명령어를 이용하여 Bundler를 설치합니다.

Bundler 설치 확인 명령어

bundler -v

Buldler 설치 성공 시 아래와 같은 메세지가 나옵니다.

Successfully installed bundler-2.6.9
1 gem installed

A new release of RubyGems is available: 3.6.7 → 3.6.9!      
Run `gem update --system 3.6.9` to update your installation.

Gemfile.lock 생성

bundle install

터미널에서 블로그 폴더로 이동 후 위 명령어를 실행하여 Jekyll 의존성을 설치합니다.
Gemfile 파일 수정 시 bundle install 재실행이 필요합니다.

정상 설치 메시지

Fetching gem metadata from https://rubygems.org/...........
Resolving dependencies...
Fetching public_suffix 6.0.2
Fetching bigdecimal 3.1.9
...
Installing jekyll-sitemap 1.4.0
Installing jekyll-admin 0.12.0
Bundle complete! 6 Gemfile dependencies, 60 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.

GitHub Actions 워크플로우 생성

name: Build and Deploy Jekyll Site

on:
  push:
    branches: [ main ]  # 기본 브랜치가 main이 아닌 경우 수정

jobs:
  build-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout source
        uses: actions/checkout@v3

      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.1'  # 최신 버전 사용 가능
          bundler-cache: true

      - name: Install dependencies
        run: bundle install

      - name: Build the site
        run: bundle exec jekyll build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3  # gh-pages 브랜치 미사용 시 변경
        with:
          github_token: $
          publish_dir: ./_site

Git 블로그 폴더에 /.github/workflows/jekyll.yml 폴더 및 파일을 생성합니다.
이 파일은 GitHub Actions 빌드 자동화 스크립트입니다.
main 브랜치에 push 시 GitHub Actions를 통해 gh-pages 브랜치가 자동 생성되고 배포됩니다.

archive-taxonomy.html 파일 수정

카테고리 글 목록 페이지에 페이징 코드를 추가합니다.

GitHub Pages 빌드 설정 변경

GitHub 페이지 > 로그인 > 우측 상단 프로필 아이콘 > Your repositories > *.github.io 블로그 리포지토리 선택 > Settings > Pages > Source : Deploy from a branch 선택 > Branch : gh-pages 브랜치 선택 > Save

GitHub Actions 푸시 권한 설정

GitHub 페이지 > 로그인 > 우측 상단 프로필 아이콘 > Your repositories > Settings > Actions > General > 하단 Workflow permission : Read and write permissions 선택 > Save

빌드 시 403 오류 메시지

Run peaceiris/actions-gh-pages@v3
[INFO] Usage https://github.com/peaceiris/actions-gh-pages#readme
Dump inputs
Setup auth token
Prepare publishing assets
Setup Git config
Create a commit
Push the commit or tag
  /usr/bin/git push origin gh-pages
  remote: Permission to 0songha0/0songha0.github.io.git denied to github-actions[bot].
  fatal: unable to access 'https://github.com/0songha0/0songha0.github.io.git/': The requested URL returned error: 403
  Error: Action failed with "The process '/usr/bin/git' failed with exit code 128"

GitHub Actions 봇에 gh-pages 브랜치에 푸시 권한이 없어서 발생하는 403 권한 오류입니다.

최신 글