perust.github.io

lentoludens의 개인 홈페이지이자 Astro 기반 포트폴리오, 블로그, 인터넷·IT 위키입니다. 메인 페이지에는 현재 관심사, 프로젝트, 작업 원칙, 과거 퍼블리싱/프론트엔드 실습 결과물을 정리합니다. /blog에는 제작기와 실험 기록을 쌓고, /wiki에는 인터넷과 IT 관련 지식과 실행 방법을 책과 장 순서로 정리합니다.

주요 내용

• 개인 소개 및 현재 포커스
• 진행 중인 프로젝트 카드
• Markdown 기반 블로그
• 책, 부, 장 순서로 읽는 Markdown 기반 인터넷·IT 위키
• 소개, 문의, 개인정보처리방침 페이지
• sitemap, robots.txt, RSS 피드(/rss.xml) 등 검색·구독 노출을 위한 기본 파일
• 과거 웹 퍼블리싱·JavaScript 실습 아카이브 보존
• Cloudflare Worker/D1 기반 익명 댓글 초안

프로젝트 구조

.
├── src/
│   ├── content/blog/        # Markdown 블로그 글
│   ├── content/wiki-books/  # 위키 책 메타데이터
│   ├── content/wiki-pages/  # 위키 장 Markdown
│   ├── layouts/             # Astro 공통 레이아웃
│   ├── pages/               # 라우트 페이지
│   └── styles/              # 전역 스타일
├── public/
│   ├── contents/            # 기존 게임/프로그램 실습 콘텐츠
│   ├── homepage/            # 기존 퍼블리싱 실습 아카이브
│   ├── study/               # 기존 강의·학습 결과물
│   ├── robots.txt
├── comments-worker/          # 익명 댓글 Worker/D1 초안
├── astro.config.mjs
└── .github/workflows/deploy.yml

로컬 실행

npm install
npm run dev

브라우저에서 http://localhost:4321에 접속합니다.

빌드 검증

npm run build

빌드 결과는 dist/에 생성됩니다.

배포 전 SEO/GEO/AEO 메타와 JSON-LD 누락을 한 번에 점검하려면 npm run verify:seo(빌드 후 scripts/check-seo.mjs 실행, 누락 시 종료 코드 1)를 실행합니다.

블로그 글 작성

src/content/blog/YYYY-MM-DD-slug.md 파일을 추가합니다.

---
title: "글 제목"
description: "검색 결과와 글 목록에 표시될 요약"
date: "2026-06-28"
category: "Build Note"
tags: ["Astro", "GitHub Pages"]
---

본문을 Markdown으로 작성합니다.

검색엔진(SEO)·생성형 검색(GEO)·답변엔진(AEO)에 잘 읽히도록 글을 쓰는 기준은 docs/blog-seo-geo-aeo-checklist.md에 정리해 두었습니다. 메타 태그와 JSON-LD 구조화 데이터(BlogPosting·BreadcrumbList 포함), /rss.xml RSS 피드는 레이아웃과 엔드포인트에서 자동 생성되므로, 글쓴이는 frontmatter를 정확히 채우는 데 집중하면 됩니다.

OG 이미지는 자동 처리됩니다. 글에 image를 직접 지정하지 않으면 카테고리 기본 이미지, 없으면 기본 OG 이미지를 사용합니다. 카테고리·태그 목록은 정적 페이지로 자동 생성되고, updated가 있으면 sitemap lastmod에도 반영됩니다. 배포 전 npm run verify:seo로 OG 이미지, JSON-LD, RSS, 카테고리/태그 페이지를 확인합니다.

검색엔진 등록 절차는 docs/search-engine-submission-checklist.md에 정리했습니다. Google Search Console, Bing Webmaster Tools, 네이버 서치어드바이저는 계정 인증이 필요하므로 사용자가 직접 등록합니다.

위키 지식 추가

책 정보는 src/content/wiki-books/, 장 본문은 src/content/wiki-pages/{book}/에 추가합니다. 처음부터 책을 세세하게 나누지 않고 큰 범위의 책 안에서 part와 order로 주제를 구분합니다.

공개하는 모든 장에는 published, updated, lastVerified, sources를 입력합니다. published는 최초 공개일로 고정하고 이후 수정 시에는 updated만 바꿉니다. sources에는 자료명, 기관, 공식 URL, 확인일을 기록하며 최신 공식 문서와 1차 자료를 우선합니다. 확인하지 않은 내용을 목차 채우기 목적으로 추가하지 않습니다.

각 책에는 공개 장이 최소 1개 있어야 하며, 같은 part의 장은 전역 order에서 연속되어야 합니다. 기존 중간 부에 장을 추가할 때는 이후 장의 순서도 함께 조정합니다.

새 장을 추가한 뒤에는 다음 전체 게이트를 실행합니다.

npm run verify:site
npm run test:publish-policy
npm run test:browser

배포

GitHub Actions가 main 브랜치 push 시 Astro 사이트를 빌드하고 GitHub Pages에 배포합니다.

기존 GitHub Pages 설정이 main / root legacy 배포라면, Astro 전환 후에는 GitHub Pages source를 GitHub Actions로 변경해야 합니다.

댓글 기능

comments-worker/에는 Cloudflare Worker + D1 기반 익명 댓글 API 초안이 있습니다.

• 댓글은 기본적으로 승인 대기 상태로 저장됩니다.
• IP 원문은 저장하지 않고 해시와 일부 마스킹된 prefix만 저장합니다.
• 운영 배포 전 Cloudflare D1, Turnstile, Worker secret 설정이 필요합니다.

자세한 설정은 comments-worker/README.md를 참고합니다.

아카이브

기존 contents/, homepage/, study/ 콘텐츠는 public/ 아래로 이동해 배포 결과물에 그대로 포함되도록 했습니다. 메인 페이지는 최신 자기소개/프로젝트/블로그 허브 역할을 하고, 하위 폴더는 과거 작업물을 참고하기 위한 아카이브로 사용합니다.