AstroPaper 테마에서 새 글 작성하기

AstroPaper 블로그 테마에서 새 글을 작성할 때의 규칙/권장사항, 팁과 요령을 소개합니다.

Table of contents

블로그 글 작성하기

새 블로그 글을 작성하려면 src/data/blog/ 디렉토리 안에 마크다운 파일을 생성하세요.

AstroPaper v5.1.0 이전에는 모든 블로그 글이 src/data/blog/ 안에 있어야 했으며, 하위 디렉토리로 구성할 수 없었습니다.

AstroPaper v5.1.0부터는 블로그 글을 하위 디렉토리로 구성할 수 있게 되어 콘텐츠 관리가 더 쉬워졌습니다.

예를 들어, 2025 아래에 글들을 그룹화하고 싶다면 src/data/blog/2025/ 안에 넣을 수 있습니다. 이는 글의 URL에도 영향을 미치므로, src/data/blog/2025/example-post.md는 /posts/2025/example-post에서 접근할 수 있습니다.

하위 디렉토리가 글의 URL에 영향을 미치지 않게 하려면 폴더 이름 앞에 밑줄 _을 붙이면 됩니다.

# 예시: 블로그 글 구조와 URL
src/data/blog/very-first-post.md          -> mysite.com/posts/very-first-post
src/data/blog/2025/example-post.md        -> mysite.com/posts/2025/example-post
src/data/blog/_2026/another-post.md       -> mysite.com/posts/another-post
src/data/blog/docs/_legacy/how-to.md      -> mysite.com/docs/how-to
src/data/blog/Example Dir/Dummy Post.md   -> mysite.com/example-dir/dummy-post

💡 팁: 프론트매터에서 블로그 글의 슬러그를 재정의할 수도 있습니다. 자세한 내용은 다음 섹션을 참조하세요.

빌드 출력에서 하위 디렉토리 URL이 나타나지 않는 경우, node_modules를 제거하고 패키지를 재설치한 후 다시 빌드하세요.

프론트매터

프론트매터는 블로그 글(기사)에 대한 중요한 정보를 저장하는 주요 위치입니다. 프론트매터는 글의 상단에 위치하며 YAML 형식으로 작성됩니다. 프론트매터와 그 사용법에 대한 자세한 내용은 astro 문서를 참조하세요.

각 글에 대한 프론트매터 속성 목록은 다음과 같습니다.

팁! 콘솔에서 new Date().toISOString()을 실행하여 ISO 8601 날짜/시간을 얻을 수 있습니다. 따옴표는 제거해야 합니다.

프론트매터에서 title, description, pubDatetime 필드만 필수로 지정해야 합니다.

제목과 설명(발췌문)은 검색 엔진 최적화(SEO)에 중요하므로 AstroPaper는 블로그 글에 이를 포함하도록 권장합니다.

slug는 URL의 고유 식별자입니다. 따라서 slug는 고유해야 하며 다른 글과 달라야 합니다. slug의 공백은 - 또는 _로 구분해야 하지만 -를 권장합니다. 슬러그는 블로그 글 파일 이름을 사용하여 자동으로 생성됩니다. 그러나 블로그 글의 프론트매터에서 slug를 정의할 수 있습니다.

예를 들어, 블로그 파일 이름이 adding-new-post.md이고 프론트매터에서 슬러그를 지정하지 않으면 Astro는 파일 이름을 사용하여 블로그 글의 슬러그를 자동으로 생성합니다. 따라서 슬러그는 adding-new-post가 됩니다. 그러나 프론트매터에서 slug를 지정하면 기본 슬러그를 재정의합니다. Astro 문서에서 이에 대해 자세히 읽을 수 있습니다.

블로그 글에서 tags를 생략하면(즉, 태그가 지정되지 않은 경우) 기본 태그 others가 해당 글의 태그로 사용됩니다. /src/content/config.ts 파일에서 기본 태그를 설정할 수 있습니다.

// src/content/config.ts
export const blogSchema = z.object({
  // ---
  draft: z.boolean().optional(),
  tags: z.array(z.string()).default(["others"]), // "others"를 원하는 것으로 대체
  // ---
});

프론트매터 예시

다음은 글의 프론트매터 예시입니다.

# src/content/blog/sample-post.md
tags:
  - social-media
---
---
title: 글의 제목
author: 작성자 이름
pubDatetime: 2022-09-21T05:17:19Z
slug: the-title-of-the-post
featured: true
draft: false
tags:
  - 예시
  - 태그
  - 샘플
ogImage: ../../assets/images/example.png # src/assets/images/example.png
# ogImage: "https://example.org/remote-image.png" # 원격 URL
description: 이것은 예시 글의 예시 설명입니다.
canonicalURL: https://example.org/my-article-was-already-posted-here
tags:
  - social-media
---
---

목차 추가하기

기본적으로 글(기사)에는 목차(toc)가 포함되어 있지 않습니다. 목차를 포함하려면 특정 방식으로 지정해야 합니다.

h2 형식(마크다운에서 ##)으로 Table of contents를 작성하고 글에서 표시하고 싶은 위치에 배치하세요.

예를 들어, 소개 단락 바로 아래에 목차를 배치하고 싶다면(제가 보통 하는 것처럼) 다음과 같이 할 수 있습니다.

tags:
  - social-media
---
---
# 프론트매터
tags:
  - social-media
---
---

여기에 AstroPaper 블로그 테마에서 새 글을 작성할 때의 권장사항, 팁과 요령이 있습니다.

## Table of contents

<!-- 글의 나머지 부분 -->

제목

제목에 대해 한 가지 주의할 점이 있습니다. AstroPaper 블로그 글은 제목(프론트매터의 title)을 글의 주요 제목으로 사용합니다. 따라서 글의 나머지 제목은 h2 ~ h6를 사용해야 합니다.

이 규칙은 필수는 아니지만, 시각적, 접근성 및 SEO 목적으로 강력히 권장됩니다.

블로그 콘텐츠용 이미지 저장하기

마크다운 파일 내에서 이미지를 저장하고 표시하는 두 가지 방법이 있습니다.

참고! 마크다운에서 최적화된 이미지를 스타일링해야 하는 경우 MDX를 사용해야 합니다.

src/assets/ 디렉토리 안에 저장 (권장)

src/assets/ 디렉토리 안에 이미지를 저장할 수 있습니다. 이 이미지는 Astro의 Image Service API를 통해 자동으로 최적화됩니다.

상대 경로나 별칭 경로(@/assets/)를 사용하여 이 이미지를 제공할 수 있습니다.

예시: /src/assets/images/example.jpg에 있는 example.jpg를 표시하고 싶다고 가정해보겠습니다.

![something](@/assets/images/example.jpg)

<!-- 또는 -->

![something](../../assets/images/example.jpg)

<!-- img 태그나 Image 컴포넌트는 작동하지 않습니다 ❌ -->
<img src="@/assets/images/example.jpg" alt="something">
<!-- ^^ 이것은 잘못된 방법입니다 -->

기술적으로는 src 아래의 모든 디렉토리에 이미지를 저장할 수 있습니다. 여기서는 src/assets를 권장하는 것뿐입니다.

public 디렉토리 안에 저장

public 디렉토리 안에 이미지를 저장할 수 있습니다. public 디렉토리에 저장된 이미지는 Astro에 의해 수정되지 않는다는 점을 기억하세요. 즉, 최적화되지 않으며 이미지 최적화는 직접 처리해야 합니다.

이러한 이미지의 경우 절대 경로를 사용해야 하며, 마크다운 주석이나 HTML img 태그를 사용하여 표시할 수 있습니다.

예시: example.jpg가 /public/assets/images/example.jpg에 있다고 가정해보겠습니다.

![something](/assets/images/example.jpg)

<!-- 또는 -->

<img src="/assets/images/example.jpg" alt="something">

보너스

이미지 압축

블로그 글에 이미지를 넣을 때(특히 public 디렉토리 아래의 이미지)는 이미지를 압축하는 것이 좋습니다. 이는 웹사이트의 전반적인 성능에 영향을 미칩니다.

이미지 압축 사이트 추천:

• TinyPng
• TinyJPG

OG 이미지

글에서 OG 이미지를 지정하지 않으면 기본 OG 이미지가 배치됩니다. 필수는 아니지만 글과 관련된 OG 이미지를 프론트매터에 지정하는 것이 좋습니다. OG 이미지의 권장 크기는 1200 X 640 픽셀입니다.

AstroPaper v1.4.0부터 OG 이미지가 지정되지 않은 경우 자동으로 생성됩니다. 공지사항을 확인하세요.