from __future__ import annotations
import argparse
import html
import re
from dataclasses import dataclass
from datetime import datetime
from pathlib import Path
from typing import Iterable
from urllib.parse import urlparse
import markdown
FRONTMATTER_RE = re.compile(r"\A---\s*\n(.*?)\n---\s*\n?", re.DOTALL)
HEADING_RE = re.compile(r"^#\s+(.+?)\s*$", re.MULTILINE)
SECTION_RE = re.compile(r"^#{1,6}\s+(.+?)\s*$", re.MULTILINE)
MARKDOWN_LINK_RE = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
BARE_URL_RE = re.compile(r"(?)]+")
@dataclass
class LinkItem:
label: str
href: str
external: bool
@dataclass
class RenderContext:
title: str
subtitle: str
issue_label: str
source_path: Path
output_path: Path
mode: str
body_html: str
toc_html: str
summary_points: list[str]
links: list[LinkItem]
section_count: int
generated_at: str
source_modified_at: str
def strip_frontmatter(text: str) -> tuple[dict[str, str], str]:
match = FRONTMATTER_RE.match(text)
if not match:
return {}, text
metadata: dict[str, str] = {}
for raw_line in match.group(1).splitlines():
if ":" not in raw_line:
continue
key, value = raw_line.split(":", 1)
metadata[key.strip().lower()] = value.strip()
return metadata, text[match.end() :]
def split_title(markdown_text: str, default_title: str) -> tuple[str, str]:
match = HEADING_RE.search(markdown_text)
if not match:
return default_title, markdown_text.lstrip()
title = match.group(1).strip()
body = markdown_text[: match.start()] + markdown_text[match.end() :]
return title, body.lstrip()
def extract_summary_points(markdown_text: str) -> list[str]:
lines = markdown_text.splitlines()
in_summary = False
points: list[str] = []
for raw_line in lines:
line = raw_line.rstrip()
stripped = line.strip()
if re.match(r"^##\s+summary\s*$", stripped, re.IGNORECASE):
in_summary = True
continue
if in_summary and stripped.startswith("#"):
break
if in_summary and line.startswith("- "):
points.append(line[2:].strip())
if len(points) == 4:
break
return points
def build_issue_label(metadata: dict[str, str]) -> str:
raw_date = metadata.get("issue date") or metadata.get("date modified") or metadata.get("date") or metadata.get("date created")
try:
issue_date = datetime.fromisoformat(raw_date).date() if raw_date else datetime.now().date()
except ValueError:
issue_date = datetime.now().date()
week = issue_date.isocalendar().week
return f"AI Tech Review Letters: Week {week:02d} ({issue_date.isoformat()})"
def extract_links(markdown_text: str) -> list[LinkItem]:
seen: set[str] = set()
items: list[LinkItem] = []
def add_item(label: str, href: str) -> None:
normalized = href.strip()
if not normalized or normalized in seen:
return
seen.add(normalized)
parsed = urlparse(normalized)
external = parsed.scheme in {"http", "https"}
final_label = label.strip() or normalized
if not external and not Path(normalized).suffix:
final_label = final_label
items.append(LinkItem(label=final_label, href=normalized, external=external))
for match in MARKDOWN_LINK_RE.finditer(markdown_text):
add_item(match.group(1), match.group(2))
for match in BARE_URL_RE.finditer(markdown_text):
url = match.group(0)
parsed = urlparse(url)
label = parsed.netloc or url
add_item(label, url)
return items
CUSTOM_BLOCK_LABELS = {
"highlight": "Highlight",
"think": "생각하기",
"thinking": "생각하기",
"evidence": "Evidence note",
"operator": "Operator note",
"pose": "Pose",
"bundle": "글묶음",
}
def preprocess_custom_blocks(markdown_text: str) -> str:
"""Convert lightweight article directives into markdown-in-html blocks."""
lines = markdown_text.splitlines()
output: list[str] = []
index = 0
while index < len(lines):
line = lines[index]
match = re.match(r"^:::\s*([a-zA-Z_-]+)(?:\s+(.*?))?\s*$", line)
if not match:
output.append(line)
index += 1
continue
block_name = match.group(1).strip().lower()
if block_name not in CUSTOM_BLOCK_LABELS:
output.append(line)
index += 1
continue
title = (match.group(2) or CUSTOM_BLOCK_LABELS[block_name]).strip()
block_lines: list[str] = []
index += 1
while index < len(lines) and lines[index].strip() != ":::":
block_lines.append(lines[index])
index += 1
if index < len(lines) and lines[index].strip() == ":::":
index += 1
safe_title = html.escape(title, quote=True)
safe_block_name = re.sub(r"[^a-z0-9_-]+", "-", block_name)
output.extend(
[
f'",
]
)
return "\n".join(output)
def build_markdown_html(markdown_text: str) -> tuple[str, str]:
renderer = markdown.Markdown(
extensions=["extra", "toc", "sane_lists", "smarty", "md_in_html"],
extension_configs={
"toc": {
"permalink": False,
"title": "",
}
},
)
body_html = renderer.convert(preprocess_custom_blocks(markdown_text))
toc_html = renderer.toc or ""
return body_html, toc_html
def format_timestamp(dt: datetime) -> str:
return dt.strftime("%Y-%m-%d %H:%M:%S")
def source_link_href(source_path: Path, output_path: Path) -> str:
try:
return source_path.relative_to(output_path.parent).as_posix()
except ValueError:
return source_path.name
def render_link_items(links: list[LinkItem]) -> str:
if not links:
return '이 리포트에서 명시적 링크가 감지되지 않았습니다.'
rendered: list[str] = []
for item in links:
target_attr = ' target="_blank" rel="noreferrer"' if item.external else ""
rendered.append(
f''
f"{html.escape(item.label)}"
)
return "\n".join(rendered)
def render_template(context: RenderContext) -> str:
if context.mode == "final-review":
return render_final_review_template(context)
summary_html = ""
if context.summary_points:
items = "\n".join(
f"{html.escape(point)}" for point in context.summary_points
)
summary_html = f"""
"""
toc_panel = ""
if context.toc_html.strip():
toc_panel = f"""
"""
link_items = render_link_items(context.links)
source_href = source_link_href(context.source_path, context.output_path)
return f"""
{html.escape(context.title)}
"""
def render_final_review_template(context: RenderContext) -> str:
summary_html = ""
if context.summary_points:
items = "\n".join(
f"{html.escape(point)}" for point in context.summary_points[:5]
)
summary_html = f"""
"""
toc_panel = ""
if context.toc_html.strip():
toc_panel = f"""
"""
link_items = render_link_items(context.links)
source_href = source_link_href(context.source_path, context.output_path)
dek_html = ""
if context.subtitle:
dek_html = f'{html.escape(context.subtitle)}
'
return f"""
{html.escape(context.title)}
AI Tech Review Letters
{html.escape(context.title)}
{dek_html}
{summary_html}
{context.body_html}
"""
def resolve_mode(source_path: Path, requested_mode: str) -> str:
if requested_mode != "auto":
return requested_mode
if source_path.stem.endswith("_final_review"):
return "final-review"
return "default"
def build_context(source_path: Path, mode: str = "auto") -> RenderContext:
raw_text = source_path.read_text(encoding="utf-8")
metadata, markdown_text = strip_frontmatter(raw_text)
title, body_markdown = split_title(markdown_text, metadata.get("title", source_path.stem))
subtitle = metadata.get("description") or metadata.get("subtitle") or ""
body_html, toc_html = build_markdown_html(body_markdown)
source_stat = source_path.stat()
generated_at = format_timestamp(datetime.now().astimezone())
source_modified_at = format_timestamp(datetime.fromtimestamp(source_stat.st_mtime).astimezone())
section_count = len(SECTION_RE.findall(body_markdown))
resolved_mode = resolve_mode(source_path, mode)
return RenderContext(
title=title,
subtitle=subtitle,
issue_label=build_issue_label(metadata),
source_path=source_path,
output_path=source_path.with_suffix(".html"),
mode=resolved_mode,
body_html=body_html,
toc_html=toc_html,
summary_points=extract_summary_points(markdown_text),
links=extract_links(markdown_text),
section_count=section_count,
generated_at=generated_at,
source_modified_at=source_modified_at,
)
def render_file(source_path: Path, mode: str = "auto") -> Path:
context = build_context(source_path, mode)
html_text = render_template(context)
context.output_path.write_text(html_text, encoding="utf-8")
return context.output_path
def parse_args(argv: Iterable[str] | None = None) -> argparse.Namespace:
parser = argparse.ArgumentParser(
description="Render one or more markdown reports into polished standalone HTML pages."
)
parser.add_argument(
"--mode",
choices=["auto", "default", "final-review"],
default="auto",
help="Rendering mode. Auto uses final-review mode for *_final_review.md.",
)
parser.add_argument("paths", nargs="+", help="Markdown files to render.")
return parser.parse_args(argv)
def main(argv: Iterable[str] | None = None) -> int:
args = parse_args(argv)
exit_code = 0
for raw_path in args.paths:
path = Path(raw_path).resolve()
if not path.exists():
print(f"[missing] {path}")
exit_code = 1
continue
if path.suffix.lower() != ".md":
print(f"[skip] {path} is not a markdown file")
exit_code = 1
continue
output_path = render_file(path, args.mode)
print(f"[rendered:{resolve_mode(path, args.mode)}] {path} -> {output_path}")
return exit_code
if __name__ == "__main__":
raise SystemExit(main())