2026년 9월 4일·6분 읽기·업데이트: 2026년 9월 29일

글 쓰기 편하자고 붙인 에디터가 제 글을 고쳐놨습니다

블로그를 만들고 제일 아쉬웠던 건 글을 쓰려면 PC를 켜야 한다는 것이었습니다.

지금 구조에서 글은 마크다운 파일이고, 그 파일은 GitHub 저장소에 들어 있습니다. 오타 하나를 고치려고 해도 에디터를 열고, 파일을 찾고, 고치고, git push를 쳐야 합니다. 출근길에 문장 하나가 떠올라도 저녁까지 기억하고 있어야 한다는 뜻이죠.

그래서 브라우저에서 글을 쓸 수 있는 화면을 붙였습니다. 주소 뒤에 /admin을 치면 로그인 창이 뜨고, 들어가면 워드 비슷한 편집기가 나옵니다. 글을 쓰고 저장 버튼을 누르면 그게 GitHub에 커밋됩니다. 폰으로도 됩니다.

붙이고 나서 기분이 좋아서, 이미 올려둔 글을 하나 열어봤습니다. 잘 나오나 보려고요.

그리고 저장 버튼을 눌렀습니다.

1. 코드블록이 회색 덩어리가 되어 있었습니다

배포가 끝나고 블로그를 열었더니 뭔가 허전했습니다. 처음엔 뭐가 달라졌는지 몰랐는데, 스크롤을 내리다 알았습니다. 코드블록에 색이 하나도 없었습니다.

원래는 yaml이면 yaml답게, ts면 ts답게 문법 강조가 들어갑니다. 그게 전부 회색 글씨 덩어리가 되어 있었어요.

그리고 더 이상한 게 있었습니다. 코드블록 바로 밑에 yaml이라는 낱말이, 아무 맥락 없이 한 문단으로 떠 있었습니다. 조금 아래에는 ts가, 그 아래에는 css가 있었습니다.

원문 파일을 열어봤습니다.

저장 전과 저장 후의 마크다운 원문 비교. 저장 전에는 코드블록 첫 줄이 백틱 세 개에 yaml이 붙어 있었는데, 저장 후에는 plain으로 바뀌었고 코드블록 아래에 yaml이라는 낱말이 별도 문단으로 남아 있다.

제가 쓴 건 이거였습니다.

```yaml
backend:
  name: github
```

저장 후에는 이렇게 되어 있었습니다.

```plain
backend:
  name: github
```

yaml

언어 표시가 plain으로 바뀌었고, 원래 자리에 있던 yaml은 본문 문단으로 밀려나 있었습니다. 글 하나에 코드블록이 예닐곱 개였으니 전부 그렇게 되어 있었습니다.

2. 왜 이런 일이 생기나

편집기에는 보통 두 가지 모드가 있습니다.

원본 모드는 마크다운을 글자 그대로 보여줍니다. 제가 메모장에서 보던 것과 똑같습니다. 서식 모드는 그걸 화면 요소로 바꿔서 보여줍니다. **굵게**가 진짜 굵은 글씨로 보이고, # 제목이 진짜 큰 글씨로 보이는 거죠. 워드처럼요.

서식 모드로 파일을 열면 이런 일이 벌어집니다.

마크다운을 읽어서 화면 요소로 변환합니다
제가 화면에서 편집합니다
저장할 때 그 화면 요소를 다시 마크다운으로 변환해서 씁니다

문제는 3번입니다. 편집기 안에 자리가 없는 정보는 2번 단계에서 이미 사라졌고, 3번에서 되살릴 방법이 없습니다. 코드블록을 표현하는 자리는 있었는데, “이건 yaml이다”라는 정보가 변환 도중에 떨어져 나간 겁니다. 편집기는 언어를 모르는 블록에 기본값 plain을 붙였고, 갈 곳 없어진 yaml이라는 글자가 본문으로 떨어졌습니다.

같은 이유로 두 가지가 더 사라졌습니다.

이미지 대체 텍스트. 눈이 안 보이는 분들이 쓰는 화면 낭독기가 읽어주는 설명입니다. 검색엔진도 이걸 봅니다. ![도식 설명](/media/a.png)이 ![](/media/a.png)가 되어 있었습니다.

문단의 줄 구조. 제 글은 한 문단이 한 줄로 이어져 있습니다. 그게 문장 중간중간 줄바꿈이 박힌 상태로 바뀌어 있었습니다. 화면에는 티가 안 나는데, 나중에 파일을 열어보면 왜 이렇게 잘려 있나 싶습니다.

저는 저장 버튼만 눌렀습니다. 글자 하나 안 바꿨어요.

(나중에 찾아보니 “불러오는 순간 편집기가 본문을 자기 방식으로 다시 쓴다”는 게 Sveltia CMS에 알려진 문제였고, 9월 말에 고쳐졌습니다. 지금은 글을 열기만 하고 본문을 안 건드리면 본문을 다시 쓰지 않습니다. 서식 모드에서 본문을 실제로 고치면 여전히 편집기 방식으로 다시 씁니다.)

3. 되돌리기

다행히 원본은 남아 있었습니다. 이 편집기는 저장할 때마다 GitHub에 커밋을 하나 만듭니다. 그 커밋 바로 앞이 제가 쓴 원본입니다.

git log --oneline -- src/content/blog/글이름.md
git diff HEAD~1 -- src/content/blog/글이름.md

git diff를 보니 바뀐 줄이 한눈에 나왔습니다. 코드블록 언어 여섯 군데, 이미지 대체 텍스트 두 군데, 문단 줄바꿈 스무 줄 남짓.

버전 관리를 쓰는 이유가 이런 순간에 있습니다. 워드 파일이었으면 그냥 날아갔을 겁니다.

4. 고친 방법

편집기 설정 파일에 한 줄을 넣었습니다.

- label: 본문
  name: body
  widget: markdown
  modes: [raw, rich_text]

modes는 이 편집기가 쓸 수 있는 모드 목록이고, 먼저 적은 게 기본값입니다. raw를 앞에 뒀으니 이제 글을 열면 마크다운 원문 그대로 열립니다.

rich_text를 아예 빼버릴까 하다가 남겼습니다. 표를 만들거나 링크를 여러 개 넣을 때는 서식 모드가 확실히 편하거든요. 다만 코드가 들어간 글에서는 안 쓰기로 했습니다. 이건 설정으로 막을 수 있는 게 아니라 제가 기억해야 하는 부분입니다.

5. 여기서 배운 것

서식 편집기는 편하려고 쓰는 겁니다. 그런데 편하다는 건 “복잡한 걸 안 보여준다”는 뜻이기도 합니다. 안 보여주는 것과 없는 것의 차이는, 저장 버튼을 누르는 순간 사라집니다.

마크다운은 반대입니다. 적힌 게 전부입니다. 불편한 대신 잃어버릴 게 없습니다.

그래서 이렇게 정리했습니다. 표현력이 좁은 도구로 넓은 원본을 건드리지 않는다. 서식 편집기는 새 글을 가볍게 쓸 때, 원본 모드는 코드가 들어간 글을 손볼 때.

블로그를 직접 만들면 이런 걸 하나씩 알게 됩니다. 남의 플랫폼을 쓸 때는 아예 겪을 일이 없는 문제인데, 대신 겪고 나면 왜 그렇게 되어 있는지가 남습니다.

혹시 정적 사이트에 글쓰기 화면을 붙이실 생각이라면, 붙이자마자 기존 글을 하나 열어서 저장해 보시고 git diff부터 확인해 보시기 바랍니다. 저처럼 배포하고 나서 알아채면 되돌리는 데 한나절이 갑니다.

고친 곳

2026년 9월 29일, 글에 붙일 참고 문서를 하나씩 다시 열어보다가 본문과 어긋나는 곳을 찾아 고쳤습니다.

“yaml을 담아둘 칸이 없었다”를 고쳤습니다. Sveltia CMS 편집기는 코드블록 언어를 담을 수 있고, 당시 제가 겪은 건 변환 과정에서 언어가 떨어지는 문제였습니다.
Sveltia CMS가 이 동작을 고친 뒤의 상황을 덧붙였습니다.

참고한 문서

Sveltia CMS 문서 — RichText 필드 (modes) — 4번. 먼저 적은 모드가 기본으로 열림
Sveltia CMS 문서 — Markdown 필드 — 4번. widget: markdown은 RichText의 별칭
Sveltia CMS 문서 — Backends — 3번. 저장할 때마다 저장소에 커밋되는 구조
Sveltia CMS 커밋 — 불러오기만 해도 본문을 다시 쓰던 문제 수정 — 1·2번. “저장만 했는데 바뀌었다”가 알려진 문제였다는 기록