Firefly 블로그 가이드

새 글 만들기#

글은 src/content/posts/ 아래에 Markdown 또는 MDX 파일로 작성한다. 스크립트를 사용하면 기본 Frontmatter가 들어간 파일을 만들 수 있다.

1
pnpm new-post my-new-post

직접 파일을 만들 때는 다음 정도로 시작하면 충분하다.

1
---
2
title: 새 글 제목
3
published: 2026-08-24
4
description: 글 목록과 검색 결과에 표시할 짧은 설명
5
image: ./images/cover.avif
6
tags: [개발, 기록]
7
category: 개발
8
draft: false
9
slug: my-new-post
10
---

자주 사용하는 필드는 다음과 같다.

slug는 한 번 공개한 뒤 바꾸면 기존 링크가 깨질 수 있으므로 짧은 영문과 하이픈 조합으로 처음부터 정해 두는 편이 좋다.

글을 시리즈로 묶기#

연속해서 읽을 글은 같은 series 이름을 지정하고 seriesOrder로 순서를 정한다.

1
series: Unreal Engine 네트워킹
2
seriesOrder: 1

시리즈가 지정된 글에는 같은 시리즈의 글 목록이 표시된다. /series/에서는 전체 시리즈를 글 수가 많은 순서로 보여 주며, 각 시리즈 안에서는 seriesOrder가 작은 글부터 정렬한다. seriesOrder를 생략한 글은 순서를 지정한 글 뒤에 배치된다.

프로젝트 작성하기#

프로젝트는 블로그 글과 별도로 src/content/projects/ 아래에 .md 또는 .mdx 파일로 작성한다. 프로젝트 목록의 카드와 상세 상단은 Frontmatter를 사용하고, 상세 하단에는 Markdown 본문을 README처럼 표시한다. 페이지 사용 여부는 src/config/siteConfig.ts의 pages.projects로 정한다.

이 절은 upstream의 프로젝트 작성 예제를 한국어로 옮겨 통합한 내용이다. 실제 파일 구성은 Copy Selection Context의 src/content/projects/copy-selection-context.md와 src/content/projects/images/copy-selection-context.webp를 참고하면 된다.

1
---
2
title: "Copy Selection Context"
3
published: 2026-02-18
4
draft: false
5
description: "JetBrains IDE에서 파일 경로, 줄 번호와 코드를 함께 복사하는 플러그인. AI에 전달할 코드 문맥을 준비할 때 사용한다."
6
image: "images/copy-selection-context.webp"
7
lang: ko
8
tags:
9
  - jetbrains-plugin
10
  - developer-tools
11
link:
12
  - label: "GitHub"
13
    icon: "fa7-brands:github"
14
    value: "https://github.com/hon454/copy-selection-context"
15
  - label: "JetBrains Marketplace"
16
    value: "https://plugins.jetbrains.com/plugin/30262-copy-selection-context"
17
---

Markdown과 MDX#

대부분의 글은 .md로 충분하다. 제목, 목록, 인용문, 표, 링크, 이미지와 코드 블록 같은 일반적인 Markdown 문법을 그대로 사용할 수 있다.

1
## 소제목
2

3
- 첫 번째 항목
4
- 두 번째 항목
5

6
> 인용문
7

8
[링크](https://example.com)
9
![대체 텍스트](./images/example.avif)

Astro나 Svelte 컴포넌트를 글 안에서 직접 사용해야 할 때만 .mdx를 선택한다. MDX 파일에서는 컴포넌트를 가져온 뒤 JSX 형태로 배치할 수 있다.

1
import Badge from "@components/common/Badge.astro";
2

3
<Badge>MDX에서 렌더링한 배지</Badge>

알림 상자와 확장 요소#

중요한 설명은 Admonition 문법으로 강조할 수 있다.

1
:::tip[작은 팁]
2
독자가 바로 실행할 수 있는 내용을 짧게 적는다.
3
:::
4

5
:::warning
6
되돌리기 어렵거나 주의가 필요한 내용을 적는다.
7
:::

note, tip, info, warning, danger 유형을 사용할 수 있다. 모양은 src/config/siteConfig.ts의 Markdown 관련 설정에서 GitHub, Obsidian, VitePress, Docusaurus 테마 중 하나로 선택한다.

GitHub 저장소 카드는 저장소 주소를 반복해서 설명하는 대신 다음처럼 넣는다.

1
::github{repo="CuteLeaf/Firefly"}

긴 설명을 접어 둘 때는 HTML의 details 요소도 유용하다.

1
<details>
2
  <summary>자세히 보기</summary>
3

4
  접혀 있을 내용
5
</details>

코드 블록#

Firefly의 코드 블록은 Expressive Code를 기반으로 한다. 언어 이름만 붙여도 구문 강조가 적용되고, 제목·줄 번호·강조·추가와 삭제 표시를 함께 사용할 수 있다.

1
```ts title="example.ts" showLineNumbers {2} ins={3}
2
const message = "Firefly";
3
console.log(message);
4
export default message;
5
```

긴 코드의 일부는 collapse로 접을 수 있다.

1
```ts collapse={1-5, 20-30}
2
// 긴 예제 코드
3
```

여러 언어 또는 패키지 관리자 명령을 나란히 보여 줄 때는 MDX의 탭 컴포넌트를 사용할 수 있지만, 한두 개의 짧은 명령이라면 일반 코드 블록이 읽기 쉽다.

수식#

KaTeX 문법으로 인라인 수식과 블록 수식을 작성할 수 있다. 문장 안에서는 $E = mc^2$처럼 쓰고, 독립된 식은 $$로 감싼다.

1
원의 넓이는 $A = \pi r^2$이다.
2

3
$$
4
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
5
$$

실제 렌더링 결과는 다음과 같다.

원의 넓이는 $A = \pi r^2$이다.

Mermaid와 PlantUML 다이어그램#

간단한 흐름도나 문서에 가까운 다이어그램은 Mermaid가 편하다.

1
```mermaid
2
flowchart LR
3
  Draft[초안 작성] --> Review[검토]
4
  Review --> Build[빌드]
5
  Build --> Publish[배포]
6
```

UML 표기나 복잡한 소프트웨어 구조를 표현할 때는 PlantUML을 사용할 수 있다.

1
```plantuml
2
@startuml
3
actor Writer
4
participant Firefly
5
participant Astro
6

7
Writer -> Firefly: Markdown 작성
8
Firefly -> Astro: 콘텐츠 빌드
9
Astro --> Writer: 정적 사이트 생성
10
@enduml
11
```

다이어그램은 한 글에 너무 많이 넣으면 빌드 시간과 가독성이 모두 나빠질 수 있다. 본문을 보조하는 한두 개의 핵심 그림에 사용하는 편이 좋다.

Wiki Link로 글 연결하기#

Obsidian에서 글을 관리한다면 Wiki Link 문법을 그대로 사용할 수 있다.

1
[[cognitive-surrender]]
2
[[cognitive-surrender|AI와 함께 코딩하며 느낀 점]]
3
[[cognitive-surrender#압도되는-것과-항복하는-것|관련 문단으로 이동]]

파일 경로나 파일 이름을 기준으로 연결하며, 표시 제목과 제목 앵커도 지정할 수 있다. 현재 페이지 안의 제목으로 이동할 때는 [[#제목|표시 문구]] 형태를 사용한다.

이미지 첨부를 뜻하는 Obsidian의 ![[image.png]] 문법은 지원 대상이 아니므로 일반 Markdown 이미지 문법을 사용한다.

이미지와 동영상#

글과 함께 관리하는 이미지는 글 파일을 기준으로 상대 경로를 사용한다.

1
![이미지 설명](./images/example.avif)

public 아래의 파일은 /images/example.avif처럼 루트 경로로 참조한다. 중요한 글자나 로고가 있는 표지는 목록과 그리드 양쪽에서 잘리지 않도록 중앙에 충분한 여백을 둔다.

YouTube처럼 임베드 코드를 제공하는 서비스는 HTML을 Markdown에 직접 넣을 수 있다.

1
<iframe
2
  width="100%"
3
  height="468"
4
  src="https://www.youtube.com/embed/VIDEO_ID"
5
  title="YouTube video player"
6
  allowfullscreen
7
></iframe>

외부 플레이어는 개인정보 보호, 자동 재생, 모바일 크기와 로딩 비용을 함께 확인해야 한다.

비밀번호로 글 보호하기#

Frontmatter에 password를 넣으면 Firefly가 빌드 과정에서 본문을 암호화한다.

1
password: "긴 비밀번호"
2
passwordHint: "나만 알아볼 수 있는 힌트"

방문자가 올바른 비밀번호를 입력하면 브라우저에서 내용을 복호화한다. 비밀번호 자체를 저장소에 커밋하는 구조이므로 진짜 비밀이나 민감한 자료를 보관하는 용도로 생각해서는 안 된다. 제한적으로 공유할 글을 가볍게 가리는 기능에 가깝다.

레이아웃 설정#

사이트 전체 설정은 주로 src/config에서 관리한다.

• siteConfig.ts: 사이트 정보, 글 목록, 내비게이션과 페이지 기능
• sidebarConfig.ts: 사이드바 위치와 위젯 구성
• backgroundWallpaper.ts: 배경 이미지와 전체 화면 효과
• commentConfig.ts: 댓글 제공자와 글별 댓글 동작
• fontConfig.ts: 글꼴과 로딩 방식

사이드바는 왼쪽, 오른쪽 또는 양쪽에 둘 수 있다.

1
export const sidebarLayoutConfig = {
2
  enable: true,
3
  position: "left",
4
  noSidebarContentWidth: 0.6,
5
};

표시할 위젯이 없는 사이드바 열은 접힌다. noSidebarContentWidth는 사이드바가 없는 페이지의 본문 너비 비율이며, 생략하거나 1 이상으로 설정하면 전체 너비를 사용한다.

글 목록은 목록형과 그리드형을 선택할 수 있다.

1
postListLayout: {
2
  defaultMode: "grid",
3
  mobileDefaultMode: "list",
4
  coverPosition: "right",
5
  grid: {
6
    masonry: true,
7
    columnWidth: 320,
8
  },
9
},

설정을 바꿀 때는 타입 정의와 실제 설정 모듈을 함께 확인한다. 스크롤이나 전체 화면 배경 효과는 모바일 성능에 직접 영향을 주므로 시각적인 변화만 보고 값을 크게 올리지 않는다.

발행 전 확인#

글을 추가하거나 설정을 바꾼 뒤에는 다음 명령을 순서대로 실행한다.

1
pnpm check
2
pnpm type-check
3
pnpm build

pnpm dev로 목록형과 그리드형 카드, 모바일 너비, 글 상세 페이지의 목차와 이미지 잘림도 확인한다. 글 표지나 생성 이미지가 바뀌었다면 pnpm lqips가 갱신한 src/constants/lqips.json도 함께 검토한다.

정리#

이 글은 Firefly의 모든 기능을 복제한 문서가 아니다. 내 블로그에서 실제로 사용하는 작성 흐름과 잊기 쉬운 문법을 한곳에 모은 개인 메모다. 테마가 업데이트되면서 세부 옵션이 달라질 수 있으므로 다음 순서로 확인한다.

1. 현재 저장소의 src/config와 타입 정의
2. Firefly 공식 문서
3. Firefly GitHub 저장소
4. Astro 자체 동작은 Astro 공식 문서

예제 글 여러 개가 아카이브를 채우는 대신, 앞으로는 이 글을 실제 사용 경험에 맞춰 조금씩 고쳐 나갈 생각이다.