AstroPaper 테마에 새 글 추가하기

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

블로그 글 작성하기

새 블로그 글을 작성하려면 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/posts/docs/how-to
src/data/blog/Example Dir/Dummy Post.md   -> mysite.com/posts/example-dir/dummy-post

팁: 블로그 글의 slug를 frontmatter에서 직접 지정할 수도 있습니다. 자세한 내용은 다음 섹션을 참고하세요.

빌드 결과에 하위 디렉토리 URL이 나타나지 않으면, node_modules를 삭제하고 패키지를 다시 설치한 후 빌드하세요.

Frontmatter

Frontmatter는 블로그 글에 대한 주요 정보를 저장하는 핵심 영역입니다. Frontmatter는 글의 최상단에 위치하며 YAML 형식으로 작성됩니다. Frontmatter와 그 사용법에 대한 자세한 내용은 Astro 문서를 참고하세요.

다음은 각 글의 frontmatter 속성 목록입니다.

팁! 콘솔에서 new Date().toISOString()을 실행하면 ISO 8601 형식의 일시를 얻을 수 있습니다. 다만 따옴표는 제거하세요.

Frontmatter에서 title, description, pubDatetime 필드만 필수로 지정해야 합니다.

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

slug는 URL의 고유 식별자입니다. 따라서 slug는 다른 글과 중복되지 않는 고유한 값이어야 합니다. slug의 공백은 - 또는 _로 구분해야 하지만 -를 권장합니다. Slug는 블로그 글 파일 이름을 사용하여 자동으로 생성됩니다. 하지만 블로그 글의 frontmatter에서 slug를 직접 정의할 수도 있습니다.

예를 들어, 블로그 파일 이름이 adding-new-post.md이고 frontmatter에서 slug를 지정하지 않으면, Astro가 파일 이름을 사용하여 자동으로 slug를 생성합니다. 따라서 slug는 adding-new-post가 됩니다. 하지만 frontmatter에서 slug를 지정하면, 기본 slug가 덮어씌워집니다. 이에 대한 자세한 내용은 Astro 문서에서 확인할 수 있습니다.

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

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

Frontmatter 예시

다음은 글의 frontmatter 예시입니다.

---
title: The title of the post
author: your name
pubDatetime: 2022-09-21T05:17:19Z
slug: the-title-of-the-post
featured: true
draft: false
tags:
  - some
  - example
  - tags
ogImage: ../../assets/images/example.png # src/assets/images/example.png
# ogImage: "https://example.org/remote-image.png" # 원격 URL
thumbnail: ../../assets/images/example-thumb.png # 카드 썸네일
# thumbnail: "https://example.org/remote-thumb.png" # 원격 URL
description: This is the example description of the example post.
canonicalURL: https://example.org/my-article-was-already-posted-here
---src/data/blog/sample-post.md

목차 추가하기

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

마크다운에서 h2 형식(## )으로 목차를 작성하고, 글에서 목차가 나타나길 원하는 위치에 배치하세요.

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

---
# frontmatter
---

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

## 목차

<!-- 나머지 글 내용 -->

제목(Heading)

제목에 대해 알아두어야 할 점이 있습니다. AstroPaper 블로그 글은 제목(frontmatter의 title)을 글의 메인 제목으로 사용합니다. 따라서 글의 나머지 제목은 h2 ~ h6을 사용해야 합니다.

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

구문 강조(Syntax Highlighting)

AstroPaper는 기본 구문 강조 도구로 Shiki를 사용합니다. AstroPaper v5.4부터는 @shikijs/transformers를 사용하여 코드 블록을 더욱 향상시킵니다. 사용하지 않으려면 다음과 같이 간단히 제거할 수 있습니다.

pnpm remove @shikijs/transformers

// ...
import {
  transformerNotationDiff,
  transformerNotationHighlight,
  transformerNotationWordHighlight,
} from "@shikijs/transformers";

export default defineConfig({
  // ...
  markdown: {
    remarkPlugins: [remarkToc, [remarkCollapse, { test: "목차" }]],
    shikiConfig: {
      // 더 많은 테마는 https://shiki.style/themes 를 참고하세요
      themes: { light: "min-light", dark: "night-owl" },
      defaultColor: false,
      wrap: false,
      transformers: [
        transformerFileName(),
        transformerNotationHighlight(),
        transformerNotationWordHighlight(),
        transformerNotationDiff({ matchAlgorithm: "v3" }),
      ],
    },
  },
  // ...
}astro.config.ts

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

마크다운 파일에서 이미지를 저장하고 표시하는 두 가지 방법을 소개합니다.

참고! 마크다운에서 최적화된 이미지에 스타일을 적용해야 한다면 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 이미지를 frontmatter에 지정하는 것이 좋습니다. OG 이미지의 권장 크기는 1200 X 640 px입니다.

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