[블로그 설정] Jekyll에서 URL 미리보기 적용하기

URL 미리보기(Link preview)는 단순히 링크 텍스트를 나열하는 대신, 링크된 페이지의 제목, 설명, 썸네일 이미지를 시각적으로 보여주는 것이다. 그러나 Jekyll로 만든 블로그에서는 URL 미리보기 기능이 없어서 이를 직접 적용해야 한다. 아래는 jekyll-linkpreview 플러그인을 활용해 이를 구현하고, Chirpy 테마 사용 시 발생할 수 있는 목차(TOC) 충돌 문제를 해결하는 방법이다.

1️⃣ jekyll-linkpreview 설치

1. Gemfile에 추가 : 프로젝트 루트 디렉토리의 Gemfile에 다음 라인을 추가한다.

   group :jekyll_plugins do
     gem "jekyll-linkpreview"
   end
   

2. _config.yml에 플러그인 등록 : 프로젝트 루트 디렉토리의 _config.yml 파일에 jekyll-linkpreview를 plugins 목록에 추가한다.

   plugins:
     - jekyll-linkpreview
   

3. 번들 설치 : 터미널에서 아래 명령어를 실행하여 플러그인 설치하기.

   bundle install
   

4. _cache 폴더 추가 : 프로젝트 루트 디렉토리 바로 아래에 _cache 폴더를 추가한다.

5. css 파일 추가 : 참고한 블로그에서는 새로운 파일로 추가했지만, 적용이 되지 않아 기존에 있던 파일에 아래 코드 추가하기. (파일 위치 : assets/css/style.scss)
   기본 제공 CSS 파일

    /* append your custom style below */
    .jekyll-linkpreview-wrapper {
      display: flex;
      max-width: 100%;
      max-height: 160px;
      border: 1px solid #eee; /* 변경된 테두리 */
      border-radius: 8px; /* 둥근 모서리 */
      position: relative;
      overflow: hidden; /* 이미지 둥근 모서리 처리 */
    }
   
    .jekyll-linkpreview-wrapper-inner {
      padding: 15px;
      display: flex;
      width: 100%;
      align-items: start; /* 이미지와 텍스트 영역 세로 중앙 정렬 */
    }
   
    .jekyll-linkpreview-content {
      display: flex;
      flex-direction: column;
      flex-grow: 1;
      margin-right: 16px; /* 조정된 간격 */
    }
   
    .jekyll-linkpreview-body {
      display: flex;
      flex-direction: column;
      justify-content: space-between;
      height: 100%;
    }
   
    .jekyll-linkpreview-title {
      font-size: 16px; /* 조정된 제목 크기 */
      margin: 0 0 4px; /* 조정된 간격 */
      line-height: 1.4;
      font-weight: bold; /* 제목 굵게 */
    }
   
    .jekyll-linkpreview-description {
      line-height: 1.4;
      font-size: 13px;
      margin-bottom: 8px; /* 조정된 간격 */
      color: #888; /* 설명 색상 변경 */
    }
   
    .jekyll-linkpreview-footer {
      font-size: 12px;
      text-align: left;
      color: #555;
    }
   
    .jekyll-linkpreview-image {
      flex-shrink: 0;
      height: 160px; /* 이미지 높이 조정 */
      aspect-ratio: 16 / 10;
      overflow: hidden;
      box-sizing: border-box;
      background-size: cover;
      background-position: center;
    }
   

2️⃣ jekyll-linkpreview 사용 방법

설치가 완료되면, Liquid 문법을 사용해 작성하면 된다.

{% linkpreview "https://www.google.com" %}

이렇게 하면 지정된 URL에 대한 미리보기가 자동으로 생성되어 아래와 같이 표시된다.

GitHub · Change is constant. GitHub keeps you ahead.

Join the world's most widely adopted, AI-powered developer platform where millions of developers, businesses, and the largest open source community build software that advances humanity.

github.com

3️⃣ Chirpy 테마의 목차(TOC) 충돌 문제

Chirpy 테마를 사용하는 경우, jekyll-linkpreview의 기본 출력 HTML이 목차(Table of Contents, TOC) 생성기와 충돌하여 의도치 않은 항목이 목차에 포함될 수 있다. 이는 jekyll-linkpreview가 기본적으로 링크 제목을 <h2> 태그로 렌더링하고, Chirpy의 경우 목차는 <h2> ~ <h3> 태그를 기준으로 생성되기 때문이다.

해결 방법

jekyll-linkpreview의 경우, 커스텀 템플릿을 지원하기 때문에 <h2> 태그를 제거할 수 있다.
_includes 폴더에 linkpreview.html 파일을 생성해 아래 코드를 추가한다.
해당 파일의 경우 지킬 문법을 사용하기 때문에, Liquid 문법을 사용하여 작성해야 한다.

<div class="jekyll-linkpreview-wrapper">
  <div class="jekyll-linkpreview-wrapper-inner">
    <div class="jekyll-linkpreview-content">
      <div class="jekyll-linkpreview-body">
        <div class="jekyll-linkpreview-title">
          <a href="{{ url }}" target="_blank">{{ title }}</a>
        </div>
        {% if description %}
          <div class="jekyll-linkpreview-description">{{ description }}</div>
        {% endif %}
        <div class="jekyll-linkpreview-footer">
          <a href="{{ url }}" target="_blank">{{ domain }}</a>
        </div>
      </div>
    </div>
  </div>
  {% if image %}
    <div class="jekyll-linkpreview-image" style="background-image: url('{{ image }}');"></div>
  {% endif %}
</div>

GitHub Actions 에러

• 루비 버전(2.7.8)이 너무 낮아서, 설치되지 않아 오류 발생
• Ruby 3.x로 버전을 올려서 해결
• pages-deploy.yml 파일 안에서 루비 버전을 2.7 → 3.1로 변경
  (파일 위치 : .github/workflows/pages-deploy.yml)

      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: 3.1  # 버전 변경
          bundler-cache: true
  

4️⃣ jekyll-linkpreview 주소

아래에서 상세한 설명을 확인할 수 있다.

GitHub - ysk24ok/jekyll-linkpreview: Jekyll plugin to generate link preview

Jekyll plugin to generate link preview. Contribute to ysk24ok/jekyll-linkpreview development by creating an account on GitHub.

github.com