새 포스트 작성하기

게시 2019/08/08

By dakim

22 분읽는 시간

새 포스트 작성하기

해당 글은 Chirpy 템플릿의 Writing a New Post를 번역하였습니다. 오역 및 오류가 있을 수 있으므로 원글을 찾아보시는 걸 추천드립니다.

제목과 파일 경로

YYYY-MM-DD-TITLE.EXTENSION 형식의 새 파일을 생성한 후, 루트 디렉터리의 _posts 폴더에 넣으세요. 여기서 EXTENSION은 반드시 md 또는 markdown 중 하나여야 합니다. 파일 생성 시간을 절약하고 싶다면, Jekyll-Compose 플러그인을 사용하는 것도 고려해보세요.

Front Matter

기본적으로, 포스트 상단에 아래와 같이 Front Matter를 작성해야 합니다:

  
---
title: TITLE
date: YYYY-MM-DD HH:MM:SS +/-TTTT
categories: [TOP_CATEGORY, SUB_CATEGORY]
tags: [TAG]     # TAG는 소문자로 작성해야 합니다.
---

포스트의 layout 값은 기본적으로 post로 설정되어 있으므로, Front Matter 블록에 layout 변수를 따로 추가할 필요가 없습니다.

날짜의 타임존

포스트의 발행 날짜를 정확하게 기록하려면, _config.yml 파일에서 timezone을 설정하는 것 뿐만 아니라, 각 포스트의 Front Matter 블록에 있는 date 변수에도 타임존 정보를 함께 입력해야 합니다. 형식은 +/-TTTT이며, 예를 들어 +0900처럼 작성합니다.

카테고리 및 태그

각 포스트의 categories는 최대 두 개의 요소만 포함하도록 설계되어 있으며, tags의 요소 개수는 0개에서 무한대까지 가능합니다. 예를 들면 다음과 같습니다:

  
---
categories: [Animal, Insect]
tags: [bee]
---

작성자 정보

포스트의 작성자 정보는 일반적으로 Front Matter 에 따로 입력할 필요가 없습니다. 기본적으로 설정 파일의 social.name과 social.links의 첫 번째 항목에서 정보를 가져옵니다. 하지만 다음과 같이 직접 지정하여 덮어쓸 수도 있습니다:

_data/authors.yml 파일에 작성자 정보를 추가하세요. (만약 이 파일이 없다면, 새로 만들어도 괜찮습니다.)

  
<author_id>:
  name: <full name>
  twitter: <twitter_of_author>
  url: <homepage_of_author>

그리고 아래와 같이 author를 사용해 한 명의 작성자를 지정하거나, authors를 사용해 여러 명의 작성자를 지정할 수 있습니다:

  
---
author: <author_id>                     # 한 명 지정 시
# or
authors: [<author1_id>, <author2_id>]   # 여러 명 지정 시
---

참고로, author 키도 여러 명의 작성자를 지정할 수 있습니다.

_data/authors.yml 파일에서 작성자 정보를 불러오면, 페이지에 twitter:creator 메타 태그가 추가되어 Twitter Cards를 다채롭게 만들고 SEO에도 도움이 됩니다.

Post Description

기본적으로, 포스트의 첫 문장들이 홈페이지의 포스트 목록, Further Reading 섹션, RSS 피드의 XML 등에서 요약으로 사용됩니다. 만약 자동 생성된 설명 대신 직접 설명을 지정하고 싶다면, Front Matter 의 description 필드를 아래와 같이 사용하면 됩니다:

  
---
description: 포스트의 간단한 요약.
---

또한, description에 입력한 내용은 해당 포스트 페이지의 제목 아래에도 표시됩니다.

목차(Table of Contents)

기본적으로 목차(TOC) 는 포스트의 오른쪽 패널에 표시됩니다. 만약 사이트 전체에서 목차를 비활성화하고 싶다면, _config.yml 파일에서 toc 변수를 false로 설정하세요.
특정 포스트에서만 목차를 끄고 싶다면, 해당 포스트의 Front Matter에 아래와 같이 추가하면 됩니다:

  
---
toc: false
---

댓글(Comments)

댓글에 대한 전체 설정은 _config.yml 파일의 comments.provider 옵션에서 정의됩니다. 이 변수에 댓글 시스템을 지정하면, 모든 포스트에 댓글 기능이 활성화됩니다.

특정 포스트에서만 댓글을 비활성화하고 싶다면, 해당 포스트의 Front Matter에 아래와 같이 추가하세요:

  
---
comments: false
---

Media

Chirpy 에서는 이미지, 오디오, 비디오를 모두 미디어 리소스(media resources)로 지칭합니다.

URL Prefix

포스트에서 여러 미디어 리소스의 URL 접두사를 반복해서 정의해야 하는 번거로움을 줄이기 위해, 두 가지 파라미터를 설정할 수 있습니다.

CDN을 사용하는 경우:
미디어 파일을 CDN에 호스팅한다면, _config.yml 파일에 cdn을 지정하세요. 그러면 사이트 아바타와 포스트의 미디어 리소스 URL 앞에 CDN 도메인이 자동으로 붙습니다.
1 cdn: https://cdn.com
포스트/페이지별 리소스 경로 지정:
특정 포스트나 페이지 범위에 대해 리소스 경로 접두사를 지정하려면, 해당 포스트의 Front Matter 에 media_subpath를 설정하세요.
1 2 3 --- media_subpath: /path/to/media/ ---

이렇게 하면 site.cdn과 page.media_subpath 옵션을 각각 또는 조합해서 사용할 수 있으며, 최종 미디어 리소스 URL은 [site.cdn/][page.media_subpath/]file.ext와 같이 유연하게 구성됩니다.

이미지

캡션(Caption)

이미지의 다음 줄에 이탤릭체(기울임꼴)로 텍스트를 추가하면, 해당 텍스트가 이미지의 캡션으로 인식되어 이미지 하단에 표시됩니다.

  
![img-description](/path/to/image)
_이미지 캡션_

사이즈(Size)

이미지 로딩 시 페이지 레이아웃이 흔들리는 현상을 방지하려면, 각 이미지에 가로(width)와 세로(height) 값을 지정해주는 것이 좋습니다.

  
![Desktop View](/assets/img/sample/mockup.png){: width="700" height="400" }

SVG 이미지의 경우, 최소한 width 를 지정해야 렌더링이 정상적으로 됩니다.

Chirpy v5.0.0 부터는 height와 width 속성을 줄여서(height → h, width → w) 사용할 수 있습니다. 아래 예시는 위와 동일한 효과를 냅니다:

  
![Desktop View](/assets/img/sample/mockup.png){: w="700" h="400" }

이미지 위치(Position)

기본적으로 이미지는 가운데 정렬되지만, normal, left, right 중 하나의 클래스를 사용해 위치를 지정할 수 있습니다.

위치를 지정한 경우에는 이미지 캡션을 추가하면 안 됩니다.

Normal position
아래 예시처럼 .normal 클래스를 사용하면 이미지는 왼쪽 정렬됩니다.
1 ![Desktop View](/assets/img/sample/mockup.png){: .normal }

Float to the left

  
![Desktop View](/assets/img/sample/mockup.png){: .left }

Float to the right

  
![Desktop View](/assets/img/sample/mockup.png){: .right }

다크/라이트 모드

이미지가 다크/라이트 모드 테마 설정을 따라가도록 만들 수 있습니다. 이를 위해서는 다크 모드용 이미지와 라이트 모드용 이미지를 각각 준비한 뒤, 각 이미지에 특정 클래스(dark 또는 light)를 지정하면 됩니다:

  
![라이트 모드 전용](/path/to/light-mode.png){: .light }
![다크 모드 전용](/path/to/dark-mode.png){: .dark }

그림자(Shadow)

프로그램 창의 스크린샷 등에는 그림자 효과를 줄 수 있습니다:

  
![Desktop View](/assets/img/sample/mockup.png){: .shadow }

프리뷰 이미지(Preview Image)

포스트 상단에 이미지를 추가하고 싶다면, 해상도가 1200 x 630인 이미지를 사용하세요.
이미지의 가로세로 비율이 1.91 : 1이 아닐 경우, 이미지가 자동으로 리사이즈 및 크롭될 수 있습니다.

이 조건을 참고하여, 이미지 속성을 아래와 같이 설정할 수 있습니다:

  
---
image:
  path: /path/to/image
  alt: 이미지 대체 텍스트
---

media_subpath 도 프리뷰 이미지에 적용할 수 있습니다. 이 값을 설정한 경우, path에는 이미지 파일명만 입력하면 됩니다.

간단하게 사용하고 싶다면, 아래처럼 image에 경로만 지정해도 됩니다.

  
---
image: /path/to/image
---

LQIP(Low-Quality Image Placeholder)

프리뷰 이미지에 LQIP를 적용하려면 아래와 같이 작성하세요:

  
---
image:
  lqip: /path/to/lqip-file # 또는 base64 URI
---

LQIP는 포스트 "Text and Typography"의 프리뷰 이미지에서 확인할 수 있습니다.

일반 이미지에도 LQIP를 적용할 수 있습니다:

  
![Image description](/path/to/image){: lqip="/path/to/lqip-file" }

동영상(Video)

SNS

아래와 같은 문법으로 소셜 미디어 플랫폼의 동영상을 임베드할 수 있습니다:

  
{% include embed/{Platform}.html id='{ID}' %}

여기서 Platform은 플랫폼 이름의 소문자, ID는 동영상 ID입니다.

아래 표는 각 동영상 URL에서 필요한 두 파라미터(Platform, ID)를 어떻게 얻는지와, 현재 지원되는 동영상 플랫폼을 보여줍니다.

동영상 URL	Platform	ID
https://www.youtube.com/watch?v=H-B46URT4mg	`youtube`	`H-B46URT4mg`
https://www.twitch.tv/videos/1634779211	`twitch`	`1634779211`
https://www.bilibili.com/video/BV1Q44y1B7Wf	`bilibili`	`BV1Q44y1B7Wf`

비디오 파일

비디오 파일을 직접 임베드 하려면 아래와 같은 문법을 사용하세요:

  
{% include embed/video.html src='{URL}' %}

여기서 URL은 비디오 파일의 경로(예: /path/to/sample/video.mp4)입니다.

임베드된 비디오 파일에 추가 속성을 지정할 수도 있습니다. 사용 가능한 전체 속성 목록은 다음과 같습니다.

poster='/path/to/poster.png' — 비디오가 로딩되는 동안 표시되는 포스터 이미지
title='Text' — 비디오 아래에 표시되는 제목(이미지와 동일한 형식)
autoplay=true — 비디오가 준비되는 즉시 자동 재생
loop=true — 비디오가 끝나면 자동으로 처음부터 반복 재생
muted=true — 처음에 음소거 상태로 재생
types — 추가 비디오 포맷의 확장자를 |로 구분해 지정(이 파일들은 주 비디오 파일과 동일한 디렉터리에 있어야 함)

위의 모든 속성을 사용하는 예시는 다음과 같습니다:

  
{%
  include embed/video.html
  src='/path/to/video.mp4'
  types='ogg|mov'
  poster='poster.png'
  title='Demo video'
  autoplay=true
  loop=true
  muted=true
%}

오디오

오디오 파일을 직접 임베드하려면 아래와 같은 문법을 사용하세요:

  
{% include embed/audio.html src='{URL}' %}

여기서 URL은 오디오 파일의 경로(예: /path/to/audio.mp3)입니다.

임베드된 오디오 파일에 추가 속성을 지정할 수도 있습니다. 사용 가능한 전체 속성 목록은 다음과 같습니다.

title='Text' — 오디오 아래에 표시되는 제목(이미지와 동일한 형식)
types — 추가 오디오 포맷의 확장자를 |로 구분해 지정(이 파일들은 주 오디오 파일과 동일한 디렉터리에 있어야 함)

위의 모든 속성을 사용하는 예시는 다음과 같습니다:

  
{%
  include embed/audio.html
  src='/path/to/audio.mp3'
  types='ogg|wav|aac'
  title='Demo audio'
%}

고정 포스트

여러 개의 포스트를 홈페이지 상단에 고정할 수 있으며, 고정된 포스트들은 발행일 기준으로 최신 순(내림차순)으로 정렬됩니다. 아래와 같이 설정하면 고정 포스트 기능이 활성화됩니다:

  
---
pin: true
---

프롬프트(Prompts)

프롬프트에는 tip, info, warning, danger의 네 가지 유형이 있습니다. 이 프롬프트들은 blockquote에 prompt-{type} 클래스를 추가하여 생성할 수 있습니다. 예를 들어, info 타입의 프롬프트는 아래와 같이 작성합니다:

> 프롬프트 예시 문장입니다.
{: .prompt-info }

문법(Syntax)

인라인 코드(Inline Code)

`inline code part`

파일 경로 하이라이트(Filepath Highlight)

`/path/to/a/file.extend`{: .filepath}

코드 블록(Code Block)

마크다운 기호 ```를 사용해 아래와 같이 쉽게 코드 블록을 만들 수 있습니다:

  
```
이것은 플레인텍스트 코드 스니펫입니다.
```

언어 지정(Specifying Language)

```{language} 이런 식으로 코드 문법 하이라이트 기능을 사용할 수 있습니다:

  
```yaml
key: value
```

Jekyll 태그 {% highlight %}는 이 테마에서 호환되지 않습니다.

라인 번호(Line Number)

기본적으로 plaintext, console, terminal을 제외한 모든 언어의 코드 블록에는 라인 번호가 표시됩니다. 코드 블록의 라인 번호를 숨기고 싶다면, nolineno 클래스를 추가하세요:

  
```shell
echo 'No more line numbers!'
```
{: .nolineno }

파일명 지정

코드 블록 상단에 언어명이 표시되는 것을 파일명으로 바꾸고 싶다면, file 속성을 추가하면 됩니다:

  
```shell
# content
```
{: file="path/to/file" }

Liquid 코드

Liquid 코드를 보여주고 싶다면, {% raw %}와 {% endraw %}로 감싸주세요:

  
{% raw %}
```liquid
{% if product.title contains 'Pack' %}
  This product's title contains the word Pack.
{% endif %}
```
{% endraw %}

또는 포스트의 YAML 블록에 render_with_liquid: false(Jekyll 4.0 이상 필요)를 추가해도 됩니다.

수식표현(Mathematics)

Chirpy 테마에서는 MathJax 를 이용해 수식(수학)을 표현할 수 있습니다. 성능상의 이유로 기본적으로 수식 기능이 비활성화되어 있으며, 아래와 같이 활성화할 수 있습니다:

  
---
math: true
---

수식 기능을 활성화한 후에는 다음과 같은 문법으로 수식을 작성할 수 있습니다.

수식 작성 방법

블록 수식(Block math)
$$ 수식 $$ 형태로, 반드시 $$ 앞뒤에 빈 줄이 있어야 합니다.
- 식 번호 삽입
  $$\begin{equation} 수식 \end{equation}$$ 형태로 작성합니다.
- 식 번호 참조
  수식 블록 내에 \label{eq:label\_name}을 추가하고, 본문에서는 \eqref{eq:label_name}으로 참조할 수 있습니다.
인라인 수식(Inline math, 문장 중간)
$$ 수식 $$을 사용하며, 앞뒤에 빈 줄 없이 작성합니다.
인라인 수식(Inline math, 리스트 등에서)
\$$ 수식 $$처럼 첫 $를 이스케이프하여 사용합니다.

  
<!-- 블록 수식, 반드시 빈 줄 유지 -->

$$
LaTeX_math_expression
$$

<!-- 식 번호, 반드시 빈 줄 유지 -->

$$
\begin{equation}
  LaTeX_math_expression
  \label{eq:label_name}
\end{equation}
$$

본문에서 \eqref{eq:label_name}로 참조할 수 있습니다.

<!-- 인라인 수식(문장 중간), 빈 줄 없이 -->

"Lorem ipsum dolor sit amet, $$ LaTeX_math_expression $$ consectetur adipiscing elit."

<!-- 인라인 수식(리스트 등), 첫 $ 이스케이프 -->

1. \$$ LaTeX_math_expression $$
2. \$$ LaTeX_math_expression $$
3. \$$ LaTeX_math_expression $$

v7.0.0부터 MathJax 의 설정 옵션은 assets/js/data/mathjax.js 파일로 이동되었습니다. 필요에 따라 extensions등을 추가하거나 옵션을 변경할 수 있습니다. chirpy-starter로 사이트를 빌드하는 경우, gem 설치 디렉터리(명령어: bundle info --path jekyll-theme-chirpy)에서 해당 파일을 복사해 사용하세요.

Mermaid

Mermaid 는 텍스트 기반의 다이어그램(플로우차트, 시퀀스 다이어그램, 클래스 다이어그램 등)을 쉽게 그릴 수 있는 JavaScript 기반 도구입니다. Chirpy 테마에서 Mermaid 다이어그램을 사용하려면, 포스트의 YAML 블록에 아래와 같이 추가하세요:

  
---
mermaid: true
---

이후 마크다운에서 다른 코드 블록과 동일하게, 아래와 같이 작성하면 Mermaid 다이어그램이 렌더링됩니다:

  
```
```mermaid 
graph TD
  A[Client] --> B[Load Balancer] 
  B --> C[Server01] 
  B --> D[Server02] ```
```

Learn More

Jekyll 포스트에 대해 더 자세히 알고 싶다면 Jekyll Docs: Posts를 참고하세요. 이 문서에서는 포스트 파일 작성 규칙, _posts 폴더 구조, Front Matter 설정, 태그와 카테고리 사용법, 이미지 및 리소스 포함 방법, 포스트 인덱스 생성, 발췌문(excerpt) 활용, 임시글(draft) 관리 등 Jekyll 블로그 포스트와 관련된 다양한 정보를 제공합니다.

Blogging

tutorial