기술 블로그 및 문서를 위한 JSON-LD 구조화 데이터와 Sitemap 자동 생성Automated JSON-LD Structured Data and Sitemap Generation for Technical Docs

from __future__ import annotations
import json
from pathlib import Path
from xml.sax.saxutils import escape

SITE_ORIGIN = "https://www.lysc.kr"
STUDIO_NAME = "LYSC STUDIO"

def build_tech_article_json_ld(doc: dict) -> str:
    """기술 문서용 Schema.org TechArticle 구조화 데이터를 JSON 문자열로 생성합니다."""
    canonical_url = f"{SITE_ORIGIN}/docs/{doc['category']}/{doc['slug']}"
    payload = {
        "@context": "https://schema.org",
        "@type": "TechArticle",
        "headline": doc["title"],
        "description": doc.get("summary", ""),
        "url": canonical_url,
        "datePublished": doc.get("date", "2026-10-09"),
        "dateModified": doc.get("updated", doc.get("date", "2026-10-09")),
        "author": {"@type": "Organization", "name": STUDIO_NAME, "url": f"{SITE_ORIGIN}/"},
        "publisher": {"@type": "Organization", "name": STUDIO_NAME, "url": f"{SITE_ORIGIN}/"},
        "inLanguage": "ko",
    }
    return json.dumps(payload, ensure_ascii=False, indent=2)

def build_verified_sitemap(repo_root: Path, docs_index: list[dict]) -> str:
    """디스크에 실제 HTML 파일이 존재하는 문서만 선별하여 sitemap.xml을 생성합니다."""
    entries: list[str] = []
    for doc in docs_index:
        html_file = repo_root / "docs" / doc["category"] / f"{doc['slug']}.html"
        if not html_file.exists():
            continue  # 404 유발 항목 자동 배제
        loc = escape(f"{SITE_ORIGIN}{doc['url']}")
        lastmod = doc.get("updated") or doc.get("date") or "2026-10-09"
        entries.append(
            f"  <url>\n"
            f"    <loc>{loc}</loc>\n"
            f"    <lastmod>{lastmod}</lastmod>\n"
            f"    <changefreq>monthly</changefreq>\n"
            f"    <priority>0.8</priority>\n"
            f"  </url>\n"
        )
    return (
        '<?xml version="1.0" encoding="UTF-8"?>\n'
        '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n'
        + "".join(entries)
        + "</urlset>\n"
    )

from __future__ import annotations
import json
from pathlib import Path
from xml.sax.saxutils import escape

SITE_ORIGIN = "https://www.lysc.kr"
STUDIO_NAME = "LYSC STUDIO"

def build_tech_article_json_ld(doc: dict) -> str:
    """Generate Schema.org TechArticle structured data as a JSON string."""
    canonical_url = f"{SITE_ORIGIN}/docs/{doc['category']}/{doc['slug']}"
    payload = {
        "@context": "https://schema.org",
        "@type": "TechArticle",
        "headline": doc["title"],
        "description": doc.get("summary", ""),
        "url": canonical_url,
        "datePublished": doc.get("date", "2026-10-09"),
        "dateModified": doc.get("updated", doc.get("date", "2026-10-09")),
        "author": {"@type": "Organization", "name": STUDIO_NAME, "url": f"{SITE_ORIGIN}/"},
        "publisher": {"@type": "Organization", "name": STUDIO_NAME, "url": f"{SITE_ORIGIN}/"},
        "inLanguage": "ko",
    }
    return json.dumps(payload, ensure_ascii=False, indent=2)

def build_verified_sitemap(repo_root: Path, docs_index: list[dict]) -> str:
    """Generate sitemap.xml including only documents whose HTML files exist on disk."""
    entries: list[str] = []
    for doc in docs_index:
        html_file = repo_root / "docs" / doc["category"] / f"{doc['slug']}.html"
        if not html_file.exists():
            continue  # Automatically exclude missing files that would return 404
        loc = escape(f"{SITE_ORIGIN}{doc['url']}")
        lastmod = doc.get("updated") or doc.get("date") or "2026-10-09"
        entries.append(
            f"  <url>\n"
            f"    <loc>{loc}</loc>\n"
            f"    <lastmod>{lastmod}</lastmod>\n"
            f"    <changefreq>monthly</changefreq>\n"
            f"    <priority>0.8</priority>\n"
            f"  </url>\n"
        )
    return (
        '<?xml version="1.0" encoding="UTF-8"?>\n'
        '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n'
        + "".join(entries)
        + "</urlset>\n"
    )