From ed0d8ff73f1b71b058703fd110ec378827e0685d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EC=9C=A4=ED=98=81=EC=A4=80?= Date: Tue, 3 Nov 2026 15:05:00 +0900 Subject: [PATCH 1/2] =?UTF-8?q?feat(seo):=20=EA=B3=B5=ED=86=B5=20SEO=20?= =?UTF-8?q?=EC=B2=98=EB=A6=AC=EC=99=80=20=EC=A3=BC=EC=A0=9C=EB=B3=84=20?= =?UTF-8?q?=EC=9D=BD=EA=B8=B0=20=EC=95=88=EB=82=B4=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 8 +- docs/seo.md | 31 +++++ index.html | 24 +--- package.json | 2 +- scripts/prerender.mjs | 114 +++++++++-------- scripts/seo-metadata.test.mjs | 27 ++++ scripts/seo.test.mjs | 68 ++++++++++ scripts/sitemap-lastmod.test.mjs | 2 +- src/components/Sidebar.tsx | 4 +- src/components/TopicGuides.tsx | 24 ++++ src/data/page-updates.ts | 3 +- src/data/topics.ts | 150 ++++++++++++++++++++++ src/entry-server.tsx | 201 +++++++++-------------------- src/hooks/useMetaTags.ts | 163 ++++++------------------ src/i18n/translations.ts | 13 +- src/lib/page-seo.ts | 28 +++++ src/lib/post-seo.ts | 15 +++ src/lib/route-modules.ts | 6 + src/lib/seo.ts | 96 ++++++++++++++ src/lib/structured-data.ts | 40 +++++- src/pages/AboutPage.tsx | 3 +- src/pages/AnalyticsPage.tsx | 5 +- src/pages/HomePage.tsx | 10 +- src/pages/PostPage.tsx | 19 +-- src/pages/PostsPage.tsx | 7 +- src/pages/PrivacyPage.tsx | 8 +- src/pages/SearchPage.tsx | 9 +- src/pages/SeriesPage.tsx | 7 +- src/pages/TagsPage.tsx | 7 +- src/pages/TopicPage.tsx | 82 ++++++++++++ src/pages/TopicsPage.tsx | 40 ++++++ src/routes.server.tsx | 4 + src/routes.tsx | 2 + tests/browser/topics-seo.spec.ts | 79 ++++++++++++ vite.config.ts | 209 +------------------------------ 35 files changed, 907 insertions(+), 603 deletions(-) create mode 100644 docs/seo.md create mode 100644 scripts/seo-metadata.test.mjs create mode 100644 src/components/TopicGuides.tsx create mode 100644 src/data/topics.ts create mode 100644 src/lib/page-seo.ts create mode 100644 src/lib/post-seo.ts create mode 100644 src/lib/seo.ts create mode 100644 src/pages/TopicPage.tsx create mode 100644 src/pages/TopicsPage.tsx create mode 100644 tests/browser/topics-seo.spec.ts diff --git a/AGENTS.md b/AGENTS.md index 3461705..cdc1971 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -88,6 +88,8 @@ React + TypeScript + Vite로 구축된 개인 기술 블로그. GitHub Pages 커 | `/` | HomePage | 최신글 5개, 인기글 Top 5, 블로그 통계 | | `/posts` | PostsPage | 전체 글 목록 (리스트/그리드) | | `/posts/:slug` | PostPage | 글 상세 (마크다운 렌더링) | +| `/topics` | TopicsPage | 주제별 안내 목록 | +| `/topics/:slug` | TopicPage | 인증·Spring AI·클라우드 이전 읽기 안내 | | `/tags` | TagsPage | 태그별 필터링 | | `/series` | SeriesPage | 시리즈별 필터링 | | `/search` | SearchPage | 고급 검색 | @@ -130,8 +132,10 @@ publishDate: "2025-12-01" # optional - 예약 발행 - draft/scheduled 글은 production 메타데이터·본문·검색 인덱스에서 자동 필터링 ### SEO -- `useMetaTags()` 훅으로 페이지별 title, description, OG 태그 설정 -- `vite.config.ts`에서 빌드 시 sitemap.xml, rss.xml 자동 생성 +- `src/lib/seo.ts`의 공통 사이트 설정·정규화·메타태그 규칙을 초기 HTML과 `useMetaTags()` 훅에서 공유 +- `src/entry-server.tsx`의 발행 경로 목록으로 `scripts/prerender.mjs`에서 sitemap.xml, 언어별 rss.xml 생성 +- 주제 안내는 `src/data/topics.ts`에서 한·영 내용·읽기 순서·실제 수정일을 관리하고 발행된 같은 언어의 글만 연결 +- SEO 변경 후 `pnpm build`, `pnpm test:seo`, `pnpm test:sitemap-lastmod`, `pnpm check:internal-links` 실행; 상세 규칙은 `docs/seo.md` 참고 - `src/entry-server.tsx` + `scripts/prerender.mjs`로 주요 라우트를 hydrated SSG HTML로 생성 - 빌드 후 `dist/404.html`은 NotFound SSR HTML로 생성해 GitHub Pages SPA fallback의 hydration mismatch 방지 diff --git a/docs/seo.md b/docs/seo.md new file mode 100644 index 0000000..fa16922 --- /dev/null +++ b/docs/seo.md @@ -0,0 +1,31 @@ +# SEO 생성과 주제별 안내 + +React/Vite와 hydrated SSG 구조를 유지한다. Jekyll SEO Tag의 사이트 기본값 + 페이지별 정보 패턴을 참고하며, 테마나 플러그인 자체는 추가하지 않는다. + +## 공통 처리 + +- `src/lib/seo.ts`: 사이트 이름·기본 설명·이미지, canonical 정규화, 메타태그, hreflang, 언어별 RSS 링크의 공통 규칙. +- `src/lib/page-seo.ts`: 홈·글 목록·태그·시리즈·소개 등 고정 페이지의 제목·설명·언어 연결을 공유한다. +- `src/lib/post-seo.ts`: 게시글 제목·설명·발행일·수정일·실제 번역 연결을 서버와 클라이언트에서 공유한다. +- `src/hooks/useMetaTags.ts`: 같은 규칙을 클라이언트 이동에 적용한다. 이전 페이지의 관리 대상 태그를 교체하며 구조화 데이터는 React 페이지가 소유한다. +- `src/entry-server.tsx`: 프리렌더할 경로와 발행된 글 목록을 제공한다. +- `scripts/prerender.mjs`: 공통 규칙으로 초기 HTML을 만들고, 동일한 경로 목록에서 사이트맵과 언어별 RSS를 생성한다. Vite 설정에서 별도로 Markdown을 파싱하지 않는다. +- `src/lib/structured-data.ts`: 공통 사이트 설정을 사용해 글·컬렉션·탐색 경로 데이터를 생성한다. + +사이트맵에는 noindex 경로를 넣지 않는다. 초안·예약 글·미번역 안내는 발행 목록에서 제외하며, hreflang에는 실제로 발행된 언어만 연결한다. canonical은 후행 슬래시를 통일하고 fragment를 제거한다. 기존 필터 쿼리의 noindex 정책은 유지한다. + +RSS에는 게시글만 넣으며 안내 페이지는 사이트맵과 일반 링크로 발견할 수 있게 한다. 게시글의 최초 발행일과 실제 수정일은 보존한다. 페이지 수정일은 `src/data/page-updates.ts`, 새 안내의 수정일은 안내 데이터에 명시하며 빌드 시간으로 갱신하지 않는다. + +## 주제 안내 + +`/topics/`와 `/en/topics/`에서 인증, Spring AI, 클라우드 이전 안내로 이동한다. 각 안내는 별도 주소, 소개, 대상 독자, 핵심 질문, 읽기 순서와 글별 추천 이유를 갖는다. 홈·사이드바에서 안내로, 안내에서 발행된 같은 언어의 글로, 글에서 안내로 연결한다. + +안내를 추가하려면 `src/data/topics.ts`의 `TOPICS`에 안정적인 slug와 한·영 내용을 작성한다. 연결할 글은 실제 slug를 사용한다. 해당 언어에 발행되지 않은 글과 그 글만 있는 섹션은 표시하지 않는다. 새로운 주제가 독립적으로 설명할 가치가 있을 때만 추가하며 모든 태그에 안내를 자동 생성하지 않는다. + +## 검증 + +`pnpm build` 후 `pnpm test:seo`, `pnpm test:sitemap-lastmod`, `pnpm check:internal-links`를 실행한다. 이동·언어·hydration 변경은 `pnpm test:browser`로 확인한다. SEO 검사는 사이트맵과 HTML의 canonical·언어 연결 일치, RSS와 발행 글의 일치, 안내의 실제 링크와 구조화 데이터, 글에서 안내로 돌아오는 링크를 확인한다. 브라우저 검사는 초기 HTML과 hydration 후 메타정보, 글·안내 간 이동, 언어 전환, 모바일 폭과 없는 주소의 404를 확인한다. + +검사 통과는 Google 색인이나 순위 상승을 뜻하지 않는다. 배포 후에는 Search Console의 Google 선택 canonical, 색인 상태, 검색 노출과 클릭을 별도로 확인한다. 이번 구현은 색인 요청을 자동 제출하지 않는다. + +참고: [Jekyll SEO Tag](https://github.com/jekyll/jekyll-seo-tag), [Jekyll Sitemap](https://github.com/jekyll/jekyll-sitemap), [Google canonical 안내](https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls), [다국어 연결 안내](https://developers.google.com/search/docs/specialty/international/localized-versions). diff --git a/index.html b/index.html index 717146c..ffdf3b9 100644 --- a/index.html +++ b/index.html @@ -7,26 +7,10 @@ - Devy 블로그 — 백엔드·인프라·AI 개발 기록 | Devy Archive - - - - - - - - - - - - - - - - - - - + + Devy Archive + + diff --git a/package.json b/package.json index c5ab6f6..52a0d44 100644 --- a/package.json +++ b/package.json @@ -14,7 +14,7 @@ "test:post-dates": "node --test scripts/post-dates.test.mjs", "test:charts": "node --test scripts/markdown-chart.test.mjs", "test:loading": "node --test scripts/async-loader.test.mjs scripts/loading.test.mjs", - "test:seo": "node --test scripts/seo.test.mjs", + "test:seo": "node --test scripts/seo.test.mjs scripts/seo-metadata.test.mjs", "test:sitemap-lastmod": "node --test scripts/sitemap-lastmod.test.mjs", "test:analytics": "node --test scripts/analytics.test.mjs", "test:rendering": "node --test scripts/rendering.test.mjs", diff --git a/scripts/prerender.mjs b/scripts/prerender.mjs index 1d79ce9..d20b433 100644 --- a/scripts/prerender.mjs +++ b/scripts/prerender.mjs @@ -1,13 +1,13 @@ import fs from "node:fs" import path from "node:path" import { fileURLToPath } from "node:url" -import { getPrerenderRoutes, render, preparePostContentForPrerender, getPostHydrationData } from "../dist-ssr/entry-server.js" +import { getPrerenderRoutes, render, preparePostContentForPrerender, getPostHydrationData, renderSeoHead, siteConfig as SITE, getFeedPosts, resolveSeo, escapeMarkup } from "../dist-ssr/entry-server.js" const __dirname = path.dirname(fileURLToPath(import.meta.url)) const rootDir = path.resolve(__dirname, "..") const distDir = path.resolve(rootDir, "dist") const template = fs.readFileSync(path.resolve(distDir, "index.html"), "utf-8") -const baseUrl = "https://dev.devy.dev" +const baseUrl = SITE.url function escapeAttr(value) { return value @@ -17,19 +17,6 @@ function escapeAttr(value) { .replace(/>/g, ">") } -function toFullTitle(title) { - return title ? `${title} | Devy Archive` : "Devy Archive" -} - -function toCanonicalPath(routePath) { - if (routePath === "/") return "/" - return routePath.endsWith("/") ? routePath : `${routePath}/` -} - -function toAbsoluteUrl(routePath) { - return `${baseUrl}${toCanonicalPath(routePath)}` -} - function safeJsonLd(jsonLd) { return JSON.stringify(jsonLd).replace(/[^<]*<\/title>/, `${escapeAttr(fullTitle)}`) - .replace(/()/, - `$1\n ` - ) - } + const head = renderSeoHead({ ...route, url: route.path, alternateUrls: route.alternates }, route.language || "ko") + if (!templateHtml.includes("")) throw new Error("Missing SEO head boundary") + return templateHtml + .replace(/[\s\S]*?/, () => `\n ${head}\n `) +} - if (route.alternates) { - const alternates = [ - route.alternates.ko ? ` ` : "", - route.alternates.en ? ` ` : "", - route.alternates.ko ? ` ` : "", - ].filter(Boolean).join("\n") - if (alternates) { - html = html.replace("", `${alternates}\n `) - } +function writeDiscoveryFiles(routes) { + const entries = routes.filter(route => !route.noindex).map(route => { + const seo = resolveSeo({ ...route, url: route.path, alternateUrls: route.alternates }, route.language || "ko") + if (new URL(seo.url).pathname !== route.path) throw new Error(`Non-canonical sitemap route: ${route.path}`) + return [ + " ", + ` ${escapeMarkup(seo.url)}`, + ...(route.lastmod ? [` ${escapeMarkup(route.lastmod)}`] : []), + ...seo.alternates.map(alt => ` `), + " ", + ].join("\n") + }) + const sitemap = ` + + +${entries.join("\n")} + +` + fs.writeFileSync(path.resolve(distDir, "sitemap.xml"), sitemap) + for (const language of ["ko", "en"]) { + const homePath = language === "en" ? "/en/" : "/" + const home = routes.find(route => route.path === homePath) + const seo = resolveSeo({ ...home, url: homePath }, language) + const items = getFeedPosts(language).map(post => { + const url = `${baseUrl}${language === "en" ? "/en" : ""}/posts/${post.slug}/` + if (!routes.some(route => route.path === new URL(url).pathname && !route.noindex)) throw new Error(`RSS target is not indexable: ${url}`) + return ` + ${escapeMarkup(post.title)} + ${escapeMarkup(url)} + ${escapeMarkup(url)} + ${escapeMarkup(post.description)} + ${new Date(post.date).toUTCString()} + ` + }) + const rss = ` + + + ${escapeMarkup(SITE.name)} + ${baseUrl}${homePath} + ${escapeMarkup(home.description)} + ${language} + +${items.join("\n")} + + +` + const feedPath = path.resolve(distDir, language === "en" ? "en/rss.xml" : "rss.xml") + fs.mkdirSync(path.dirname(feedPath), { recursive: true }) + fs.writeFileSync(feedPath, rss) } - - return html } function injectAppHtml(templateHtml, appHtml, routePath) { @@ -107,6 +109,8 @@ for (const route of routes) { fs.writeFileSync(outPath, html) } +writeDiscoveryFiles(routes) + const notFoundRoute = { path: "/404/", title: "404", diff --git a/scripts/seo-metadata.test.mjs b/scripts/seo-metadata.test.mjs new file mode 100644 index 0000000..7586a09 --- /dev/null +++ b/scripts/seo-metadata.test.mjs @@ -0,0 +1,27 @@ +import assert from "node:assert/strict" +import test from "node:test" +import { canonicalUrl, renderSeoHead, resolveSeo } from "../src/lib/seo.ts" + +test("canonical addresses normalize paths, retain legacy queries, and discard document fragments", () => { + assert.equal(canonicalUrl(), "https://dev.devy.dev/") + assert.equal(canonicalUrl("/en/topics/spring-ai#section"), "https://dev.devy.dev/en/topics/spring-ai/") + assert.equal(canonicalUrl("/tags?tag=C%2B%2B#filters:tag=java"), "https://dev.devy.dev/tags/?tag=C%2B%2B") + assert.throws(() => canonicalUrl("https://example.com/post"), /must belong/) +}) + +test("metadata escapes text and attribute values without corrupting literal replacement tokens", () => { + const html = renderSeoHead({ title: 'A & B