위키 배포 가이드 — Zensical + Firebase Hosting¶

#!/usr/bin/env python3
r"""Convert Obsidian [[wikilink]] to standard markdown links.

- 코드블록 (```...```) 과 인라인 코드 (`...`) 안의 [[...]] 는 보호
- [[name]]       → [name](name.md)
- [[name|alias]] → [alias](name.md)
- ![[image.png]] → ![image.png](image.png) (이미지 임베드)
- 백슬래시 이스케이프 \[\[name\]\] 는 변환하지 않고 \[ \] 만 풀어줌

Usage: python3 scripts/wikilinks.py <docs_dir>
"""
from __future__ import annotations

import re
import sys
from pathlib import Path

CODE_BLOCK = re.compile(r"```[\s\S]*?```")
INLINE_CODE = re.compile(r"`[^`\n]*`")
WIKILINK = re.compile(r"!?\[\[([^\[\]\n]+?)\]\]")
ESCAPED = re.compile(r"\\\[\\\[([^\n]+?)\\\]\\\]")


def _convert(match: re.Match[str]) -> str:
    raw = match.group(0)
    inner = match.group(1)
    is_embed = raw.startswith("!")
    if "|" in inner:
        target, _, alias = inner.partition("|")
    else:
        target, alias = inner, inner
    target = target.strip()
    alias = alias.strip()
    if is_embed:
        return f"![{alias}]({target})"
    # 이미 .md 확장자가 있거나 URL인 경우 그대로
    if target.startswith(("http://", "https://", "/")) or target.endswith(".md"):
        return f"[{alias}]({target})"
    return f"[{alias}]({target}.md)"


def _unescape(match: re.Match[str]) -> str:
    return f"[[{match.group(1)}]]"


def convert(text: str) -> str:
    placeholders: list[str] = []

    def stash(m: re.Match[str]) -> str:
        placeholders.append(m.group(0))
        return f"\x00WIKI_STASH_{len(placeholders) - 1}\x00"

    text = CODE_BLOCK.sub(stash, text)
    text = INLINE_CODE.sub(stash, text)
    text = WIKILINK.sub(_convert, text)
    text = ESCAPED.sub(_unescape, text)

    def restore(m: re.Match[str]) -> str:
        return placeholders[int(m.group(1))]

    text = re.sub(r"\x00WIKI_STASH_(\d+)\x00", restore, text)
    return text


def main(docs_dir: str) -> None:
    root = Path(docs_dir)
    converted = 0
    for md_file in root.rglob("*.md"):
        original = md_file.read_text(encoding="utf-8")
        new = convert(original)
        if new != original:
            md_file.write_text(new, encoding="utf-8")
            converted += 1
    print(f"  wikilinks 변환: {converted}개 파일")


if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("Usage: python3 scripts/wikilinks.py <docs_dir>", file=sys.stderr)
        sys.exit(1)
    main(sys.argv[1])

"""MkDocs hook — 페이지별 검색 메타데이터.

- description: frontmatter에 없으면 H1 뒤 첫 문단에서 뽑는다(전 페이지가 site_description 하나를 공유하던 문제).
- sitemap lastmod: 빌드 날짜 대신 frontmatter `updated`.
- robots noindex: 저자용 운영 메모(backlog·plan-*) — sitemap에서도 빠진다(overrides/sitemap.xml).
"""
import re

MAX_LEN = 155
NOINDEX = re.compile(r"^(backlog|plan-.*)\.md$")
SKIP = re.compile(r"^(#|\||```|~~~|<|!!!|\?\?\?|!\[|---|\{|:::|\s)")
CLEAN = [
    (re.compile(r"[[([^\]|]+)\|([^\]]+)]]"), r"\2"),
    (re.compile(r"[[([^\]]+)]]"), r"\1"),
    (re.compile(r"!\[^\](^\.md)*\]\([^)]*\)"), ""),
    (re.compile(r"\[([^\]]+)\]\([^)]*\)"), r"\1"),
    (re.compile(r"<[^>]+>"), ""),
    (re.compile(r"\{:[^}]*\}"), ""),
    (re.compile(r"[*_`]{1,3}"), ""),
    (re.compile(r"^>\s*(\[![^\]]+\]\s*)?"), ""),
    (re.compile(r'"'), "'"),  # Material이 content="…"를 이스케이프하지 않음
    (re.compile(r"\s+"), " "),
]


def describe(markdown, title=""):
    h1 = re.search(r"^# .*$", markdown, re.M)  # 첫 H1 = 페이지 제목(코드블록 속 `# 주석`보다 앞)
    body = markdown[h1.end():] if h1 else markdown
    para, fallback, fence = [], [], False
    for line in body.splitlines() + [""]:
        if line.lstrip().startswith(("```", "~~~")):
            fence = not fence
            if para:
                break
            continue
        if fence:
            continue
        if not line.strip():
            if para:
                break
            continue
        if SKIP.match(line):
            if para:
                break
            continue
        if line.lstrip().startswith((">", "- ", "* ")) or re.match(r"\d+\. ", line):
            if not para and not fallback:
                fallback.append(re.sub(r"^\s*([-*]|\d+\.)\s+", "", line))
            if para:
                break
            continue
        para.append(line)
    text = " ".join(para or fallback)
    for pat, rep in CLEAN:
        text = pat.sub(rep, text)
    text = text.strip()
    if title and (len(text) < 40 or text.endswith((":", "다음과 같습니다."))):
        text = f"{title} — {text}" if text else title
    if len(text) > MAX_LEN:
        text = text[:MAX_LEN].rsplit(" ", 1)[0].rstrip(",.·—:;(") + "…"
    return text


def on_page_markdown(markdown, page, config, files):
    meta = page.meta
    if meta.get("updated"):
        page.update_date = str(meta["updated"])
    if not meta.get("description"):
        desc = describe(markdown, str(meta.get("title", "")))
        if desc:
            meta["description"] = desc
    if NOINDEX.match(page.file.src_uri):
        meta["robots"] = "noindex"
    return markdown


if __name__ == "__main__":
    md = "# 제목\n\n[[a|링크]]와 **굵게** `코드` 설명입니다.\n둘째 줄.\n\n## 다음\n본문"
    assert describe(md) == "링크와 굵게 코드 설명입니다. 둘째 줄.", describe(md)
    assert describe("# t\n\n> 인용만\n\n| 표 |") == "인용만"
    assert describe("# t\n\n" + "가" * 10 + " " + "나" * 200).endswith("…")
    assert describe('# t\n\n```\n# 주석\n코드\n```\n\n"인용" 문장', "t") == "t — '인용' 문장"
    print("ok")

"""MkDocs hook — frontmatter `created`가 NEW_DAYS일 이내인 페이지의 메뉴 제목에 🆕를 붙인다.

빌드 시점 기준이므로, 배지는 30일이 지난 뒤 다음 빌드·배포에서 사라진다.
"""
import datetime as dt
import re

NEW_DAYS = 30
CREATED = re.compile(r"^created:\s*(\d{4}-\d{2}-\d{2})", re.M)


def on_nav(nav, config, files):
    today = dt.date.today()
    for page in nav.pages:
        try:
            head = open(page.file.abs_src_path, encoding="utf-8").read(2000)
        except OSError:
            continue
        m = CREATED.search(head)
        if m and page.title and (today - dt.date.fromisoformat(m.group(1))).days <= NEW_DAYS:
            page.title = "🆕 " + page.title
    return nav

"""Zensical은 MkDocs 훅을 실행하지 않는다 — seo.py·new_badge.py가 하던 일을 빌드 전후 단계로 옮긴다.

  pre  <docs> <mkdocs.yml> <out.yml> : docs/*.md frontmatter에 description·robots를 써 넣고,
                                       created가 30일 이내인 페이지 nav 제목에 🆕를 붙인 설정을 out.yml로 쓴다.
  post <docs> <site> <site_url>      : frontmatter `updated`를 lastmod로 쓰는 sitemap.xml을 만든다(robots 페이지 제외).
"""
import datetime as dt
import json
import os
import re
import sys

sys.path.insert(0, os.path.dirname(__file__))
from seo import NOINDEX, describe  # noqa: E402
from new_badge import NEW_DAYS  # noqa: E402

FM = re.compile(r"\A---\n(.*?)\n---\n", re.S)


def field(fm, key):
    m = re.search(rf"^{key}:\s*['\"]?(.*?)['\"]?\s*$", fm, re.M)
    return m.group(1) if m else ""


def pages(docs):
    for root, _, names in os.walk(docs):
        for n in names:
            if n.endswith(".md"):
                path = os.path.join(root, n)
                yield os.path.relpath(path, docs), path


def pre(docs, config, out):
    today = dt.date.today()
    new = set()
    for rel, path in pages(docs):
        text = open(path, encoding="utf-8").read()
        m = FM.match(text)
        fm = m.group(1) if m else ""
        body = text[m.end():] if m else text
        add = []
        if not field(fm, "description"):
            desc = describe(body, field(fm, "title"))
            if desc:
                add.append(f"description: {json.dumps(desc, ensure_ascii=False)}")
        if NOINDEX.match(rel) and not field(fm, "robots"):
            add.append("robots: noindex")
        created = field(fm, "created")
        if re.fullmatch(r"\d{4}-\d{2}-\d{2}", created) and (today - dt.date.fromisoformat(created)).days <= NEW_DAYS:
            new.add(rel)
        if add:
            fm = "\n".join(([fm] if fm else []) + add)
            open(path, "w", encoding="utf-8").write(f"---\n{fm}\n---\n{body}")

    # nav 줄 `- 제목: 파일.md` 의 제목 앞에 🆕
    def badge(m):
        if m.group(3) not in new:
            return m.group(0)
        title = m.group(2)
        title = f"{title[0]}🆕 {title[1:]}" if title[:1] in "'\"" else f"🆕 {title}"
        return f"{m.group(1)}{title}: {m.group(3)}"

    cfg = open(config, encoding="utf-8").read()
    cfg = re.sub(r"^(\s*- )([^:\n]+): (\S+\.md)\s*$", badge, cfg, flags=re.M)
    open(out, "w", encoding="utf-8").write(cfg)


def post(docs, site, site_url):
    base = site_url.rstrip("/") + "/"
    urls = []
    for rel, path in sorted(pages(docs)):
        m = FM.match(open(path, encoding="utf-8").read())
        fm = m.group(1) if m else ""
        if field(fm, "robots"):
            continue
        slug = rel[:-3]
        if not os.path.exists(os.path.join(site, slug if slug != "index" else "", "index.html")):
            continue  # 빌드되지 않은 md
        loc = base if slug == "index" else f"{base}{slug}/"
        lastmod = field(fm, "updated")
        urls.append(f"  <url>\n    <loc>{loc}</loc>\n" + (f"    <lastmod>{lastmod}</lastmod>\n" if lastmod else "") + "  </url>")
    xml = '<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n' + "\n".join(urls) + "\n</urlset>\n"
    open(os.path.join(site, "sitemap.xml"), "w", encoding="utf-8").write(xml)
    print(f"sitemap.xml: {len(urls)} URL")


if __name__ == "__main__":
    {"pre": pre, "post": post}[sys.argv[1]](*sys.argv[2:])