네이버 블로그 링크 카드 자동 발행, API로 못 만드는 카드를 붙여넣기로

네이버 블로그 링크 카드는 왜 문제였나?

네이버 블로그 링크 카드는 API로 만들 수 없고, 자동 발행에서 카드를 얻는 길은 빈 문단에 주소 하나만 붙여 넣어 편집기가 스스로 카드를 만들게 하는 방법 하나뿐이었습니다. 2026년 9월 18일, 저희가 무인으로 발행한 네이버 블로그 글 5편을 다시 열어 보니 관련 글 링크는 본문에 주소 문자열 그대로 박혀 있었고, 소제목·인용구·구분선·링크 카드는 5편 모두 0개였습니다.

글을 읽은 대표의 지적은 두 갈래였습니다. 하나는 글 구조를 전혀 신경 쓰지 않은 듯 보인다는 점, 다른 하나는 다른 글로 이어 주는 링크를 그냥 본문에 적어 버렸다는 점이었습니다.

다른 글 유도를 그냥 링크를 본문에 적어버리면 어떡해. 에디터에서 제공하는 링크 첨부 기능을 사용해야 보기에도 예쁘게 나오지.

사람이 편집기에서 글을 쓴다면 툴바의 링크 버튼을 누르면 끝나는 일입니다. 문제는 저희 글이 사람 손을 거치지 않는다는 점이었습니다. 원고 생성기가 마크다운을 만들고, 무인 발행기가 크롬을 원격으로 조종해 편집기 화면에 그 원고를 조립한 뒤 발행 버튼까지 누릅니다. 사람이라면 1초면 끝날 버튼 하나가, 자동화에서는 어떤 경로로도 눌리지 않는 버튼일 수 있었습니다.

이 글은 그 링크 카드를 중심으로 소제목·인용구·구분선까지 자동 발행 글에 되살린 기록입니다. 같은 작업을 글 구조 관점에서 정리한 글은 네이버 블로그 글 구조 자동 발행 개선기에 따로 있고, 여기서는 자동화가 막힌 지점과 우회로, 그리고 중간에 틀렸던 판단을 더 깊게 다룹니다.

처음 잰 숫자: 상위 노출 글 9건 중 7건, 저희 글 5편 중 0편

지적이 맞는지부터 쟀습니다. 감으로 고치면 어디까지 고쳐야 하는지 정할 수 없기 때문입니다. 저희가 노리는 검색어 3종으로 네이버 검색 결과 상위 노출 글 9건을 모으고, 측정 스크립트에 구조 측정 기능을 새로 붙여 저희 발행분 5편과 같은 자로 쟀습니다.

측정 항목은 일곱 가지였습니다. 제목 길이, 소제목 수, 문단 길이 분포, 인용구 수, 구분선 수, 링크 카드 수, 이미지 수입니다. 소제목은 글자 크기를 키워 만든 형태와 편집기의 소제목 컴포넌트로 만든 형태를 둘 다 셌습니다.

• 상위 노출 글 9건 중 7건이 소제목이나 인용구 가운데 하나 이상을 썼다
• 저희 발행분 5편은 소제목 0개·인용구 0개·구분선 0개·링크 카드 0개였다
• 검색어는 3종, 측정은 상위 글과 저희 글을 같은 스크립트로 재는 방식이었다

여기서 숫자 하나는 나중에 고쳐야 했습니다. 측정 스크립트의 첫 버전은 상위 9건 모두가 구조 장치를 갖췄다고 보고했습니다. 9건 중 9건이라는 숫자는 문제를 더 크게 보이게 했고, 저희는 한동안 그 숫자를 근거로 삼았습니다. 이 숫자가 왜 틀렸는지는 가설이 틀린 지점에서 다시 적습니다.

측정 스크립트를 먼저 만든 데는 이유가 하나 더 있었습니다. 고친 뒤에도 같은 자로 다시 재야 고친 효과를 말할 수 있기 때문입니다. 상위 글을 재는 자와 저희 글을 재는 자가 다르면, 수정 후 숫자가 좋아져도 그게 글이 바뀐 탓인지 자가 바뀐 탓인지 가를 수 없습니다. 그래서 제목 길이부터 이미지 수까지 일곱 항목을 상위 검색 결과 글과 저희 글에 똑같이 적용했습니다.

반대쪽 숫자인 저희 글 0개는 처음부터 의심할 여지가 없었습니다. 5편 전부, 네 가지 장치 전부가 0이었습니다. 원고를 쓰는 쪽은 분명히 소제목을 넣었는데, 화면에는 하나도 없었습니다.

처음 세운 가설은 무엇이었나?

첫 가설은 단순했습니다. 링크 카드는 툴바의 링크 추가 기능으로 만들 수 있고, 소제목·인용구·구분선도 툴바 버튼으로 하나씩 넣으면 충분하다고 봤습니다. 사람이 하는 순서를 그대로 자동화하면 결과도 사람이 만든 글과 같아지리라는 기대였습니다.

고칠 범위를 두고는 세 안이 있었습니다.

• 1안: 지금처럼 소제목을 굵은 본문 문단으로 둔다. 지적을 그대로 무시하는 선택이라 기각
• 2안: 관련 글만 링크 카드로 바꾸고 소제목·인용구는 손대지 않는다. 지적의 절반인 구조 문제를 놓쳐 기각
• 3안: 제목 50자 상한, 소제목 컴포넌트, 리드 직후 인용구, 큰 소제목 앞 구분선, 문단 200자 분할, 관련 글 링크 카드까지 전면 개편. 채택

2안은 작업량만 보면 가장 매력적이었습니다. 대표가 직접 짚은 것은 링크였고, 링크만 카드로 바꾸면 지적에 답한 모양은 갖춰집니다. 그런데 처음 잰 숫자가 가리킨 빈자리는 링크 하나가 아니라 네 장치 전부였습니다. 상위 노출 글이 쓰는 소제목과 인용구를 놔두고 링크만 고치면, 같은 측정을 다시 돌렸을 때 저희 글은 여전히 네 칸 중 세 칸이 0으로 남습니다.

3안을 고른 뒤에도 구현 방식의 가설은 남아 있었습니다. 원고를 조립하는 도중에 툴바를 눌러 장치를 하나씩 넣는다, 구분선은 소제목마다 하나씩 넣는다, 측정 스크립트가 낸 9건 중 9건이 목표선이다. 이 세 가지가 출발 가설이었고, 셋 다 그대로 살아남지 못했습니다.

가설은 어디서 틀렸나?

첫 번째로 무너진 가설은 툴바의 링크 추가 기능이었습니다. 이 버튼을 누르면 링크 입력 칸이 아니라 글감 검색 창이 열렸고, 자동화가 보내는 합성 입력으로는 그 창에서 조회 자체가 이루어지지 않았습니다. 2회 실측했고 2회 모두 같은 자리에서 멈췄습니다.

두 번째는 조립 도중 툴바를 누르는 방식이었습니다. 원고는 문단과 그림을 번갈아 넣으며 조립하는데, 그 사이에 툴바를 누르면 커서 위치가 그림 업로드와 엉켰습니다. 소제목을 넣으려던 자리에 그림이 들어가거나 그 반대가 생기는 식입니다. 사람이 쓸 때는 눈으로 커서를 보고 바로잡지만 무인 발행기는 그럴 수 없습니다.

세 번째는 구분선이었습니다. 처음에는 소제목마다 구분선을 넣었습니다. 블로그 글로 옮겨 실은 기술 글은 섹션이 8~12개라, 구분선이 11줄까지 늘었습니다. 상위 노출 글에서 잰 구분선 최대치는 8이었습니다. 상위 글의 최대치를 넘는 구분선은 구조가 아니라 소음이었고, 결국 관련 글 앞 1회로 줄였습니다.

네 번째는 측정 스크립트 자신이었습니다. 첫 버전은 글자 크기를 키운 소제목만 셌고, 편집기 컴포넌트로 만든 소제목은 세지 못했습니다. 그런데 이 결함 때문에 숫자가 줄어든 것이 아니라 오히려 9건 중 9건으로 부풀어 있었습니다. 재측정으로 7건으로 고쳐 다시 커밋했고(PR #660), 조사 문서에도 틀린 숫자를 지우지 않고 정정 표시를 남겼습니다.

네 가지 실패에는 공통점이 있었습니다. 전부 사람이 편집기를 쓰는 방식을 그대로 옮기려 한 자리였습니다. 사람은 버튼을 누르고, 화면을 보고, 틀리면 되돌립니다. 무인 발행기에는 그 중간의 눈이 없습니다. 툴바가 창을 띄우거나 커서가 어긋나도 발행기는 알아채지 못하고 다음 단계로 넘어갑니다.

목표선이 틀려 있었다는 사실은 작아 보여도 무게가 있습니다. 9건 중 9건이 기준이었다면 구조 장치가 없는 글은 무조건 실패라는 결론이 나옵니다. 실제로는 상위 글 9건 중 2건은 그런 장치 없이도 상위에 있었습니다. 구조는 중요한 신호지만 유일한 조건은 아니라는 점을, 측정기가 틀린 덕분에 오히려 분명히 알게 됐습니다.

진짜 원인은 무엇이었나?

소제목이 사라진 원인은 원고가 아니라 변환 함수 한 곳에 있었습니다. 마크다운을 편집기용 문단으로 바꾸는 parse_markdown() 함수가 `## 소제목`을 `<p><b>…</b></p>`, 곧 굵은 본문 문단으로 바꿔 왔습니다. 원고 파일에는 소제목이 있었지만 화면에서는 본문과 같은 크기의 굵은 글씨 한 줄이었습니다. 저희 쪽 테스트는 원고를 검사했기 때문에 이 차이를 보지 못했습니다.

링크 카드가 만들어지지 않은 원인은 더 깊었습니다. 네이버 블로그 편집기의 링크 카드(oglink)에는 oglinkSign이라는 값이 붙는데, 이 값은 네이버가 발급하는 서명 토큰입니다. 문서 JSON에 카드 모양만 흉내 내어 넣어도 서명이 없으니 정상 카드가 아닙니다. 서명은 편집기가 주소를 받아 스스로 미리보기를 만들 때만 붙습니다.

정리하면 장치마다 만드는 길이 달랐습니다. 소제목·인용구·구분선은 저희가 문서 구조를 직접 바꿔도 되는 장치였고, 링크 카드는 편집기에게 만들게 해야만 하는 장치였습니다. 처음 가설은 네 장치를 모두 같은 방식, 곧 툴바 버튼으로 넣으려 했기 때문에 둘 다에서 막혔습니다.

조치: 조립은 문단으로, 승격은 한 번에, 카드는 붙여넣기로

조치는 세 프로그램에 나눠 들어갔습니다. 원고 생성기, 측정 스크립트, 무인 발행기입니다. 생성기와 측정 스크립트는 PR #657로, 측정 스크립트 정정은 PR #660으로 들어갔고, 발행기는 저장소 밖 운영 스크립트라 따로 고쳤습니다.

원고 생성기는 원고의 모양을 바꿨습니다. 제목을 50자로 자르는 함수를 넣고, 리드 바로 뒤에 인용구가 오도록 했습니다. 내용이 겹치던 “정리” 섹션을 지우고, 자주 묻는 질문은 한 단계 작은 소제목으로 바꿨습니다. 관련 글은 주소를 본문에 쓰지 않고 `[링크: URL]`이라는 자리표시자로 남겨, 발행기가 그 자리를 카드로 바꾸게 했습니다.

발행기의 핵심은 순서였습니다. 조립하는 동안에는 소제목·인용구·구분선도 평범한 문단으로 붙입니다. 툴바를 누르지 않으니 커서가 그림 업로드와 엉킬 일이 없습니다. 조립이 끝나면 브라우저 안에서 자바스크립트로 문서 JSON을 한 번 고쳐, 표시해 둔 문단들을 소제목·인용구·구분선 컴포넌트로 바꿉니다.

이 수술을 브라우저 안에서 한 번에 끝낸 데는 비용 이유가 있었습니다. 발행기가 크롬에 명령을 보내고 결과를 받는 한 번의 왕복이 약 26초 걸렸습니다. 장치마다 왕복했다면 소제목 8~12개짜리 글은 몇 분을 왕복에만 썼을 테니, 재구성 로직 전체를 브라우저로 보내 글 한 편당 왕복 1회로 줄였습니다.

링크 카드는 사람의 방식을 흉내 냈습니다. 자리표시자가 있는 위치에 빈 문단을 만들고 주소 하나만 붙여 넣은 뒤, 편집기가 oglink 카드를 만들어 낼 때까지 주기적으로 확인하며 기다립니다. 카드가 나타나면 다음 자리로 넘어갑니다. 수정 발행할 때는 기존 관련 글 블록을 통째로 지우고 새로 붙여, 카드가 두 번 생기는 일을 막았습니다.

자리표시자를 쓴 이유도 같은 데 있습니다. 생성기가 주소를 본문 문장 안에 바로 쓰면, 발행기는 그 주소가 카드로 바꿀 대상인지 본문의 일부인지 가를 수 없습니다. `[링크: URL]` 한 줄은 생성기와 발행기 사이의 약속입니다. 생성기는 카드가 들어갈 자리만 표시하고, 카드를 실제로 만드는 일은 편집기를 다루는 발행기가 맡습니다.

• 발행 전 검사에 구조 하한을 넣었다: 소제목이 2개 미만이면 발행하지 않는다
• 발행 후 감시는 발행 당시 기록이 아니라 라이브 글을 다시 조회해 구조 회귀를 판정한다
• 발행기 테스트 14개를 새 구조 규격에 맞춰 고쳤고 전부 통과했다

마지막 두 줄은 감시 쪽 수정입니다. 이전 감시는 발행할 때 남긴 검사 기록을 읽었기 때문에, 글을 새 구조로 수정 발행한 뒤에도 옛 기록의 실패 표시가 계속 경고로 남았습니다. 라이브 글을 직접 다시 재면 지금 화면에 실제로 무엇이 있는지를 봅니다.

다시 재 보니 결과는 어땠나?

검증은 이미 발행한 글로 했습니다. 기존 발행 7편을 전부 새 구조로 수정 발행하고, 라이브 글을 같은 측정 스크립트로 다시 쟀습니다. 7편 모두 통과했고, 소제목은 편당 8~12개, 링크 카드는 편당 2~3개가 화면에 있었습니다.

숫자만 믿지 않으려고 첫 편은 화면 캡처로 직접 눈으로 확인했습니다. 측정 스크립트가 한 번 9건 중 9건으로 틀린 적이 있었기 때문입니다. 측정기가 컴포넌트를 세는 방식과 사람 눈에 보이는 모양이 일치하는지를 한 편이라도 대조해 두어야, 나머지 글의 숫자를 믿을 근거가 생깁니다.

하루 전인 9월 17일에 들어간 결정도 이 결과와 맞물려 있습니다. 네이버가 외부 링크가 있는 글을 노출에서 불리하게 다룰 위험을 이유로, 블로그 원고에서 홈페이지 링크를 전부 뺐습니다. 원고 181편을 다시 만든 뒤 홈페이지 주소가 남은 원고는 0편이었고, 발행기에는 네이버 블로그 바깥 주소가 하나라도 있으면 발행을 막는 검사가 들어갔습니다.

그래서 링크 카드가 가리키는 곳은 저희가 이미 네이버에 발행한 글뿐입니다. 표를 상위 5행만 보여 주고 나머지는 홈페이지로 넘기던 장치도 쓸 수 없어, 표는 전 행을 원고에 싣습니다. 리포트 표는 최대 15행이라 블로그 화면에 그대로 실어도 무리가 없었습니다.

남는 한계는 무엇인가?

첫째, 이번 측정은 구조를 쟀지 노출을 재지 않았습니다. 상위 글과 같은 장치를 갖췄다는 사실과 상위에 오른다는 사실은 다릅니다. 상위 9건 중 2건이 구조 장치 없이도 상위에 있었다는 점이 그 차이를 보여 줍니다. 구조 개편 이후의 검색 순위 변화는 이 기록에 없습니다.

둘째, 링크 카드는 편집기의 동작에 기대고 있습니다. 빈 문단에 주소를 붙여 넣으면 카드가 생긴다는 동작은 네이버가 정한 화면 동작이지 약속된 인터페이스가 아닙니다. 그 동작이 바뀌면 발행기는 카드를 기다리다 멈출 수 있습니다(추정: 편집기 동작 변경 시나리오는 실측하지 않았습니다).

셋째, 발행 전 검사의 구조 하한은 소제목 2개뿐입니다. 링크 카드 수나 인용구 유무는 발행 전에 막지 않고, 발행 후 라이브 재조회에서 잡습니다. 이미 나간 글을 고치는 비용이 들 수 있는 구조입니다.

다섯째, 측정 스크립트도 한 번 틀렸던 도구입니다. 컴포넌트형 소제목을 세지 못하는 결함은 고쳤지만, 편집기가 새 형태의 블록을 쓰기 시작하면 같은 종류의 누락이 다시 생길 수 있습니다. 라이브 재측정이 통과했다는 판정은 측정기가 그 블록을 셀 수 있다는 전제 위에 서 있습니다. 첫 편을 눈으로 대조한 일을 앞으로도 가끔 반복해야 하는 이유입니다.

넷째, 관련 글 카드의 재료가 부족한 주제가 있습니다. 외부 링크를 뺀 뒤 관련 글은 이미 네이버에 발행한 글끼리만 잇는데, 같은 주제에 발행한 글이 없으면 관련 글 블록을 아예 생략합니다. 억지로 만들지 않기로 한 선택이지만, 그런 글에는 링크 카드가 0개로 남습니다.

자동 발행에서 링크 카드를 넣으려면 무엇부터 확인해야 하나?

이번 일에서 남은 순서는 세 가지입니다. 첫째, 넣으려는 장치가 문서 구조만 바꾸면 되는 장치인지, 플랫폼이 서명하거나 발급해야 하는 장치인지부터 가립니다. 링크 카드처럼 서명 토큰이 붙는 장치는 아무리 JSON을 정확히 흉내 내도 정상 카드가 아닙니다.

둘째, 툴바 버튼이 자동화에서 막히면 사람이 쓰는 다른 입력 경로를 찾습니다. 이번에는 붙여넣기였습니다. 조립과 서식을 한 번에 하려 하지 말고, 조립을 끝낸 뒤 서식을 한 번에 입히면 커서 문제와 왕복 비용이 함께 줄어듭니다.

셋째, 목표선을 재는 측정기부터 의심합니다. 이번에 9건 중 9건이라는 숫자는 측정기가 컴포넌트를 세지 못해서 생겼고, 고치고 나니 7건이었습니다. 원고가 아니라 라이브 화면을 다시 재고, 한 편은 눈으로 대조하는 편이 맞았습니다.

블로그 글자수 쪽 실측은 네이버 블로그 글자수 실측에 따로 정리했습니다. 네이버 블로그나 사내 콘텐츠 발행을 자동화하다 비슷한 벽에 막혀 있다면 상담 페이지에서 상황을 남겨 주셔도 좋습니다.