ar2md 0.1.0__py3-none-any.whl

ar2md/__init__.py

@@ -0,0 +1,3 @@
+"""arXiv HTML to Markdown conversion."""
+
+__all__ = []

ar2md/arxiv.lua

@@ -0,0 +1,277 @@
+local referenced_ids = {}
+local algorithm_sources = {}
+
+local function has_class(element, class_name)
+  for _, class in ipairs(element.classes or {}) do
+    if class == class_name then
+      return true
+    end
+  end
+  return false
+end
+
+local function anchor_block(identifier)
+  return pandoc.RawBlock("html", '<a id="' .. identifier .. '"></a>')
+end
+
+local function anchor_inline(identifier)
+  return pandoc.RawInline("markdown", '<a id="' .. identifier .. '"></a>')
+end
+
+local function referenced_anchor_block(identifier)
+  if identifier ~= "" and referenced_ids[identifier] then
+    return anchor_block(identifier)
+  end
+end
+
+local function internal_identifier(target)
+  local fragment = target:match("^#(.+)$")
+  if fragment then
+    return fragment
+  end
+  if target:match("^%a[%w+%.%-]*:") or target:match("^//") then
+    return nil
+  end
+  return target:match("%.html#(.+)$")
+end
+
+
+local function rewrite_link(link)
+  if link.target:match("^data:") or link.target:match("^javascript:") then
+    return {}
+  end
+
+  local identifier = internal_identifier(link.target)
+  if identifier then
+    referenced_ids[identifier] = true
+    link.target = "#" .. identifier
+  end
+
+  link.title = ""
+  link.identifier = ""
+  link.classes = {}
+  link.attributes = {}
+  return link
+end
+
+local function collect_references(document)
+  document:walk({
+    Link = function(link)
+      local identifier = internal_identifier(link.target)
+      if identifier then
+        referenced_ids[identifier] = true
+      end
+    end,
+  })
+end
+
+local function collect_algorithm_sources(document)
+  document:walk({
+    Figure = function(figure)
+      if not figure.identifier:match("^alg%d+$") then
+        return
+      end
+
+      figure:walk({
+        Link = function(link)
+          if link.target:match("^data:text/plain") then
+            local _, contents = pandoc.mediabag.fetch(link.target)
+            if contents then
+              algorithm_sources[figure.identifier] = contents
+            end
+          end
+        end,
+      })
+    end,
+  })
+end
+
+local function clean_div(div)
+  local content = div.content
+  local anchor = referenced_anchor_block(div.identifier)
+  if anchor then
+    table.insert(content, 1, anchor)
+  end
+  return content
+end
+
+local function clean_span(span)
+  if has_class(span, "ltx_ERROR") or has_class(span, "ltx_bib_cited") then
+    return {}
+  end
+
+  if has_class(span, "ltx_role_footnotemark") then
+    local mark = pandoc.utils.stringify(span.content):match("%d")
+    return pandoc.Superscript({ pandoc.Str(mark or "*") })
+  end
+
+  if has_class(span, "ltx_role_footnote") then
+    local note_content = span.content
+    while note_content[1] and note_content[1].tag == "Superscript" do
+      table.remove(note_content, 1)
+    end
+    if note_content[1] and note_content[1].tag == "Str" and note_content[1].text:match("^%d+$") then
+      table.remove(note_content, 1)
+    end
+    return pandoc.Note({ pandoc.Para(note_content) })
+  end
+
+  local content = span.content
+  if has_class(span, "ltx_font_bold") then
+    content = { pandoc.Strong(content) }
+  elseif has_class(span, "ltx_font_italic") then
+    content = { pandoc.Emph(content) }
+  elseif has_class(span, "ltx_font_typewriter") then
+    content = { pandoc.Code(pandoc.utils.stringify(content)) }
+  end
+
+  if span.identifier ~= "" and referenced_ids[span.identifier] then
+    table.insert(content, 1, anchor_inline(span.identifier))
+  end
+  return content
+end
+
+local function clean_header(header)
+  local identifier = header.identifier
+  header.identifier = ""
+  header.classes = {}
+  header.attributes = {}
+
+  local anchor = referenced_anchor_block(identifier)
+  if anchor then
+    return { anchor, header }
+  end
+  return header
+end
+
+local function clean_code(code)
+  code.identifier = ""
+  code.classes = {}
+  code.attributes = {}
+  return code
+end
+
+local function clean_code_block(code_block)
+  code_block.identifier = ""
+  code_block.classes = {}
+  code_block.attributes = {}
+  return code_block
+end
+
+local function clean_figure(figure)
+  local blocks = {}
+  local caption_text = pandoc.utils.stringify(figure.caption.long)
+  if caption_text ~= "" then
+    figure = figure:walk({
+      Image = function(image)
+        local alt_text = pandoc.utils.stringify(image.caption)
+        if alt_text == "" or alt_text == "Refer to caption" then
+          image.caption = { pandoc.Str(caption_text) }
+        end
+        return image
+      end,
+    })
+  end
+  local anchor = referenced_anchor_block(figure.identifier)
+  if anchor then
+    table.insert(blocks, anchor)
+  end
+
+  local algorithm_source = algorithm_sources[figure.identifier]
+  if algorithm_source then
+    table.insert(blocks, pandoc.CodeBlock(algorithm_source))
+  else
+    for _, block in ipairs(figure.content) do
+      table.insert(blocks, block)
+    end
+  end
+  for _, block in ipairs(figure.caption.long) do
+    table.insert(blocks, block)
+  end
+  return blocks
+end
+
+local function clean_image(image)
+  image.identifier = ""
+  image.classes = {}
+  image.attributes = {}
+  image.title = ""
+
+  if image.src:match("^data:image/") then
+    return {}
+  end
+  return image
+end
+
+local function clean_table(table_element)
+  local identifier = table_element.identifier
+
+  if has_class(table_element, "ltx_equation") then
+    local equation
+    local equation_number
+
+    table_element:walk({
+      Math = function(math)
+        equation = equation or math
+      end,
+      Str = function(text)
+        equation_number = equation_number or text.text:match("^%((%d+)%)$")
+      end,
+    })
+
+    local blocks = {}
+    if identifier ~= "" then
+      table.insert(blocks, anchor_block(identifier))
+    end
+    if equation then
+      equation.mathtype = "DisplayMath"
+      table.insert(blocks, pandoc.Para({ equation }))
+    end
+    if equation_number then
+      table.insert(blocks, pandoc.Para({ pandoc.Str("Equation (" .. equation_number .. ")") }))
+    end
+    return blocks
+  end
+
+  table_element.identifier = ""
+  table_element.classes = {}
+  table_element.attributes = {}
+
+  local anchor = referenced_anchor_block(identifier)
+  if anchor then
+    return { anchor, table_element }
+  end
+  return table_element
+end
+
+function Pandoc(document)
+  local article_blocks
+
+  document:walk({
+    Div = function(div)
+      if has_class(div, "ltx_page_content") then
+        article_blocks = div.content
+      end
+    end,
+  })
+
+  if not article_blocks then
+    error("arXiv article container (.ltx_page_content) not found")
+  end
+
+  local article = pandoc.Pandoc(article_blocks, document.meta)
+  collect_references(article)
+  collect_algorithm_sources(article)
+
+  return article:walk({
+    Code = clean_code,
+    CodeBlock = clean_code_block,
+    Div = clean_div,
+    Header = clean_header,
+    Figure = clean_figure,
+    Image = clean_image,
+    Link = rewrite_link,
+    Span = clean_span,
+    Table = clean_table,
+  })
+end

ar2md/cli.py

@@ -0,0 +1,380 @@
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+from importlib import resources
+from importlib.metadata import version
+from html.parser import HTMLParser
+from pathlib import Path
+from typing import Sequence
+
+
+ARXIV_ID_PATTERN = re.compile(
+    r"^(?:https?://(?:www\.)?arxiv\.org/(?:abs|html|pdf)/)?"
+    r"(?P<base>\d{4}\.\d{4,5})\.?v(?P<version>\d+)"
+    r"(?:\.pdf)?/?$"
+)
+
+
+class _TitleParser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__()
+        self.in_title = False
+        self.parts: list[str] = []
+
+    def handle_starttag(
+        self,
+        tag: str,
+        attrs: list[tuple[str, str | None]],
+    ) -> None:
+        if tag == "title":
+            self.in_title = True
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag == "title":
+            self.in_title = False
+
+    def handle_data(self, data: str) -> None:
+        if self.in_title:
+            self.parts.append(data)
+
+    def title(self) -> str:
+        return " ".join("".join(self.parts).split())
+
+
+def parse_arxiv_id(value: str) -> str:
+    match = ARXIV_ID_PATTERN.fullmatch(value)
+    if not match:
+        raise argparse.ArgumentTypeError(
+            "expected a versioned arXiv ID or URL, for example 1706.03762v7"
+        )
+    return f"{match.group('base')}v{match.group('version')}"
+
+
+def require_tool(name: str) -> str:
+    configured = os.environ.get(name.upper(), name)
+    executable = shutil.which(configured)
+    if not executable:
+        raise SystemExit(
+            f"{name} is required but was not found; "
+            f"install it or set {name.upper()}=/path/to/{name}"
+        )
+    return executable
+
+
+def run(command: list[str], *, cwd: Path) -> None:
+    subprocess.run(command, cwd=cwd, check=True)
+
+
+def _download_html(arxiv_id: str, host: str, wget: str, output_dir: Path) -> Path:
+    html_path = output_dir / host / "html" / f"{arxiv_id}.html"
+    url = f"https://{host}/html/{arxiv_id}"
+    completed = subprocess.run(
+        [
+            wget,
+            "--page-requisites",
+            "--convert-links",
+            "--adjust-extension",
+            "--no-parent",
+            url,
+        ],
+        cwd=output_dir,
+        text=True,
+        capture_output=True,
+    )
+    if completed.returncode:
+        raise subprocess.CalledProcessError(
+            completed.returncode,
+            completed.args,
+            output=completed.stdout,
+            stderr=completed.stderr,
+        )
+    if not html_path.is_file():
+        raise SystemExit(f"wget completed without creating {html_path}")
+
+    sys.stdout.write(completed.stdout)
+    sys.stderr.write(completed.stderr)
+    return html_path
+
+
+def _show_download_error(error: subprocess.CalledProcessError) -> None:
+    if error.stdout:
+        sys.stdout.write(error.stdout)
+    if error.stderr:
+        sys.stderr.write(error.stderr)
+
+
+def fetch_html(arxiv_id: str, wget: str, output_dir: Path) -> Path:
+    arxiv_path = output_dir / "arxiv.org" / "html" / f"{arxiv_id}.html"
+    ar5iv_path = output_dir / "ar5iv.labs.arxiv.org" / "html" / f"{arxiv_id}.html"
+    for html_path in (arxiv_path, ar5iv_path):
+        if html_path.exists():
+            print(f"Using existing HTML: {html_path}")
+            return html_path
+
+    try:
+        return _download_html(arxiv_id, "arxiv.org", wget, output_dir)
+    except subprocess.CalledProcessError as error:
+        if error.returncode != 8 or not re.search(r"(?:ERROR\s+|HTTP/\S+\s+)404\b", error.stderr or ""):
+            _show_download_error(error)
+            raise
+
+    print(
+        f"arXiv HTML is unavailable for {arxiv_id}; falling back to ar5iv.",
+        file=sys.stderr,
+    )
+    try:
+        return _download_html(arxiv_id, "ar5iv.labs.arxiv.org", wget, output_dir)
+    except subprocess.CalledProcessError as error:
+        _show_download_error(error)
+        raise
+
+
+def recover_foreign_object_content(source: str) -> tuple[str, int]:
+    svg_pattern = re.compile(
+        r'<svg\b[^>]*\bltx_picture\b[^>]*>.*?</svg>',
+        re.IGNORECASE | re.DOTALL,
+    )
+    foreign_object_pattern = re.compile(
+        r"<foreignobject\b[^>]*>(.*?)</foreignobject>",
+        re.IGNORECASE | re.DOTALL,
+    )
+    recovered_count = 0
+
+    def recover(svg_match: re.Match[str]) -> str:
+        nonlocal recovered_count
+        fragments = foreign_object_pattern.findall(svg_match.group(0))
+        if not fragments:
+            return svg_match.group(0)
+        recovered_count += 1
+        return "\n".join(fragments)
+
+    return svg_pattern.sub(recover, source), recovered_count
+
+
+def convert_html(html_path: Path, pandoc: str) -> Path:
+    output_path = html_path.with_suffix(".md")
+    temporary_path = output_path.with_suffix(".md.tmp")
+    prepared_path = html_path.with_suffix(".pandoc.html.tmp")
+    temporary_path.unlink(missing_ok=True)
+    prepared_path.unlink(missing_ok=True)
+
+    source_path = html_path
+    source = html_path.read_text(encoding="utf-8", errors="replace")
+    recovered_source, recovered_count = recover_foreign_object_content(source)
+    if recovered_count:
+        prepared_path.write_text(recovered_source, encoding="utf-8")
+        source_path = prepared_path
+
+    filter_resource = resources.files("ar2md").joinpath("arxiv.lua")
+    try:
+        with resources.as_file(filter_resource) as filter_path:
+            run(
+                [
+                    pandoc,
+                    source_path.name,
+                    "--from=html",
+                    "--to=markdown+pipe_tables+tex_math_dollars",
+                    "--wrap=none",
+                    f"--lua-filter={filter_path}",
+                    f"--output={temporary_path.name}",
+                ],
+                cwd=html_path.parent,
+            )
+        if not temporary_path.is_file() or temporary_path.stat().st_size == 0:
+            raise SystemExit("pandoc did not produce a non-empty Markdown file")
+        temporary_path.replace(output_path)
+    finally:
+        temporary_path.unlink(missing_ok=True)
+        prepared_path.unlink(missing_ok=True)
+
+    return output_path
+
+
+def extract_title(html_path: Path, markdown_path: Path) -> str:
+    parser = _TitleParser()
+    parser.feed(html_path.read_text(encoding="utf-8", errors="replace"))
+    title = re.sub(r"^\[[^\]]+\]\s*", "", parser.title())
+    if title:
+        return title
+
+    markdown = markdown_path.read_text(encoding="utf-8")
+    heading = re.search(r"^#\s+(.+?)\s*$", markdown, re.MULTILINE)
+    if heading:
+        return heading.group(1)
+    raise SystemExit(f"could not determine the paper title from {html_path}")
+
+
+def inspect_markdown(markdown_path: Path) -> list[dict[str, int]]:
+    markdown = markdown_path.read_text(encoding="utf-8")
+    warnings: list[dict[str, int]] = []
+
+    citation_placeholders = len(re.findall(r"\*{1,3}\?\*{1,3}", markdown))
+    if citation_placeholders:
+        warnings.append(
+            {
+                "code": "unresolved_citation_placeholders",
+                "count": citation_placeholders,
+            }
+        )
+
+    internal_targets = set(re.findall(r"\]\(#([^)]+)\)", markdown))
+    explicit_anchors = set(re.findall(r'<a id="([^"]+)"></a>', markdown))
+    unresolved_targets = internal_targets - explicit_anchors
+    if unresolved_targets:
+        warnings.append(
+            {
+                "code": "unresolved_internal_links",
+                "count": len(unresolved_targets),
+            }
+        )
+
+    nested_math = len(re.findall(r"\$\$\s*\$", markdown))
+    if nested_math:
+        warnings.append(
+            {
+                "code": "nested_math_delimiters",
+                "count": nested_math,
+            }
+        )
+
+    image_targets = re.findall(r"!\[[^\]]*\]\(([^)]+)\)", markdown)
+    missing_images = {
+        target
+        for target in image_targets
+        if not re.match(r"^(?:https?://|data:)", target)
+        and not (markdown_path.parent / target).is_file()
+    }
+    if missing_images:
+        warnings.append(
+            {
+                "code": "missing_local_images",
+                "count": len(missing_images),
+            }
+        )
+    return warnings
+
+
+def report_warnings(warnings: list[dict[str, int]]) -> None:
+    messages = {
+        "unresolved_citation_placeholders": (
+            "unresolved citation placeholders; the source HTML likely "
+            "contains damaged citations"
+        ),
+        "unresolved_internal_links": "unresolved internal link targets",
+        "nested_math_delimiters": "nested display-math delimiters",
+        "missing_local_images": "missing local image targets",
+    }
+    for warning in warnings:
+        print(
+            f"Warning: {warning['count']} {messages[warning['code']]}.",
+            file=sys.stderr,
+        )
+
+
+def update_index(
+    output_dir: Path,
+    arxiv_id: str,
+    title: str,
+    html_path: Path,
+    markdown_path: Path,
+    warnings: list[dict[str, int]],
+) -> Path:
+    index_path = output_dir / "index.jsonl"
+    records: dict[str, dict[str, object]] = {}
+    if index_path.exists():
+        for line_number, line in enumerate(
+            index_path.read_text(encoding="utf-8").splitlines(),
+            start=1,
+        ):
+            if not line.strip():
+                continue
+            try:
+                record = json.loads(line)
+            except json.JSONDecodeError as error:
+                raise SystemExit(
+                    f"invalid JSON in {index_path} at line {line_number}: {error.msg}"
+                ) from error
+            if not isinstance(record, dict) or not isinstance(record.get("id"), str):
+                raise SystemExit(
+                    f"invalid record in {index_path} at line {line_number}: "
+                    'expected an object with a string "id"'
+                )
+            records[record["id"]] = record
+
+    relative_html = html_path.relative_to(output_dir)
+    relative_markdown = markdown_path.relative_to(output_dir)
+    host = relative_html.parts[0]
+    records[arxiv_id] = {
+        "id": arxiv_id,
+        "title": title,
+        "source": f"https://{host}/html/{arxiv_id}",
+        "html": relative_html.as_posix(),
+        "markdown": relative_markdown.as_posix(),
+        "warnings": warnings,
+    }
+
+    temporary_path = index_path.with_suffix(".jsonl.tmp")
+    temporary_path.unlink(missing_ok=True)
+    try:
+        content = "".join(
+            json.dumps(records[record_id], ensure_ascii=False) + "\n"
+            for record_id in sorted(records)
+        )
+        temporary_path.write_text(content, encoding="utf-8")
+        temporary_path.replace(index_path)
+    finally:
+        temporary_path.unlink(missing_ok=True)
+    return index_path
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ar2md",
+        description="Download versioned arXiv HTML (with ar5iv fallback) and convert it to Markdown.",
+    )
+    parser.add_argument("paper", type=parse_arxiv_id, help="versioned arXiv ID or URL")
+    parser.add_argument(
+        "-o",
+        "--output-dir",
+        type=Path,
+        default=Path("ar2md"),
+        help="mirror root (default: ./ar2md)",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {version('ar2md')}")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    wget = require_tool("wget")
+    pandoc = require_tool("pandoc")
+    output_dir = args.output_dir.expanduser().resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        html_path = fetch_html(args.paper, wget, output_dir)
+        markdown_path = convert_html(html_path, pandoc)
+        title = extract_title(html_path, markdown_path)
+        warnings = inspect_markdown(markdown_path)
+        report_warnings(warnings)
+        index_path = update_index(
+            output_dir,
+            args.paper,
+            title,
+            html_path,
+            markdown_path,
+            warnings,
+        )
+    except subprocess.CalledProcessError as error:
+        command = Path(error.cmd[0]).name
+        parser.exit(error.returncode or 1, f"ar2md: {command} failed\n")
+
+    print(f"HTML: {html_path}")
+    print(f"Markdown: {markdown_path}")
+    print(f"Index: {index_path}")

ar2md-0.1.0.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: ar2md
+Version: 0.1.0
+Summary: Download arXiv HTML papers and convert them to LLM-ready Markdown
+Project-URL: Homepage, https://github.com/cs-giung/ar2md
+Project-URL: Repository, https://github.com/cs-giung/ar2md
+Project-URL: Issues, https://github.com/cs-giung/ar2md/issues
+Author: cs-giung
+License-Expression: MIT
+License-File: LICENSE
+Keywords: arxiv,llm,markdown,pandoc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# ar2md
+
+Download a versioned arXiv paper as HTML and convert it to LLM-ready Markdown with Pandoc. Native arXiv HTML is preferred; papers without it fall back to ar5iv.
+
+## Requirements
+
+- GNU Wget
+- Pandoc 3.x
+
+Set `WGET` or `PANDOC` to an executable path when either tool is not on `PATH`.
+
+## Run without installing
+
+```bash
+uvx ar2md 1706.03762v7
+```
+
+## Install as a uv tool
+
+```bash
+uv tool install ar2md
+ar2md 1706.03762v7
+```
+
+The PyPI distribution and installed executable are both named `ar2md`.
+
+To run an unreleased commit directly from GitHub:
+
+```bash
+uvx --from git+https://github.com/cs-giung/ar2md ar2md 1706.03762v7
+uv tool install git+https://github.com/cs-giung/ar2md
+```
+
+A version is required so that the local reference is reproducible. For convenience, the common extra-dot spelling `1706.03762.v7` is accepted and normalized to `1706.03762v7`. Versioned arXiv `abs`, `html`, and `pdf` URLs are also accepted.
+
+## Output
+
+The default mirror root is `./ar2md`. Files retain their source hostname:
+
+```text
+ar2md/
+├── index.jsonl
+├── arxiv.org/                 # preferred source
+│   ├── html/
+│   │   ├── 1706.03762v7.html
+│   │   ├── 1706.03762v7.md
+│   │   └── 1706.03762v7/
+│   └── static/
+└── ar5iv.labs.arxiv.org/      # created only for fallback papers
+    ├── html/
+    │   ├── 1503.02531v1.html
+    │   └── 1503.02531v1.md
+    └── assets/
+```
+
+Choose another mirror root with `--output-dir`:
+
+```bash
+ar2md 1706.03762v7 --output-dir papers
+```
+
+An existing HTML snapshot is reused, while Markdown is regenerated atomically on each invocation.
+
+`index.jsonl` contains one JSON object per versioned paper ID. Records are sorted by ID and replaced, rather than duplicated, when a paper is regenerated. The index is written atomically after successful conversion:
+
+```json
+{"id": "1207.0580v1", "title": "Improving neural networks by preventing co-adaptation of feature detectors", "source": "https://ar5iv.labs.arxiv.org/html/1207.0580v1", "html": "ar5iv.labs.arxiv.org/html/1207.0580v1.html", "markdown": "ar5iv.labs.arxiv.org/html/1207.0580v1.md", "warnings": [{"code": "unresolved_citation_placeholders", "count": 24}]}
+```
+
+The `html` and `markdown` paths are relative to the mirror root. The `source` field records whether the HTML came from arXiv or ar5iv. `warnings` is empty for a clean conversion.
+
+After conversion, `ar2md` checks for unresolved citation placeholders, unresolved internal links, nested display-math delimiters, and missing local images. Findings are printed to stderr and stored as structured warning counts in the index. The tool does not fabricate content that is already missing from the source HTML.
+
+## ar5iv fallback
+
+The downloader first requests `https://arxiv.org/html/<versioned-id>`. An HTTP 404 triggers a request to `https://ar5iv.labs.arxiv.org/html/<versioned-id>`; network failures and other HTTP errors do not silently switch sources. For example:
+
+```bash
+ar2md 1503.02531v1
+```
+
+The resulting HTML and Markdown are stored under `ar2md/ar5iv.labs.arxiv.org/`, making the alternate provenance explicit. A cached fallback snapshot is reused on later runs. ar5iv is a LaTeXML conversion service rather than an arXiv archival endpoint, so retain the downloaded snapshot when exact reproducibility matters.
+
+## Local development
+
+```bash
+uvx --from . ar2md 1706.03762v7
+uv tool install .
+```
+
+## Conversion
+
+The bundled Lua filter keeps the paper body while removing arXiv UI, preserves TeX math and figures, uses figure captions as descriptive image alt text, reconstructs algorithm code blocks, normalizes footnotes and equation blocks, and rewrites internal citations to valid local anchors.
+
+## Publishing
+
+Build and validate the distributions locally:
+
+```bash
+uv lock --check
+uv run python -m unittest discover -s tests -v
+uv build
+uvx twine check dist/*
+```
+
+Publishing uses PyPI Trusted Publishing. In the PyPI project or pending-publisher settings, configure:
+
+- PyPI project: `ar2md`
+- GitHub owner: `cs-giung`
+- GitHub repository: `ar2md`
+- workflow: `publish.yml`
+- environment: `pypi`
+
+Then create a GitHub release from a tag matching `v<project.version>`, such as `v0.1.0`. The release workflow checks the tag against `pyproject.toml`, runs the test suite, validates both distributions, and publishes without a long-lived API token.
+
+## License
+
+MIT

ar2md-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+ar2md/__init__.py,sha256=efZmQZqQLvUSTvkAKod-2zChpchSEOILMCkAYFsSp6g,55
+ar2md/arxiv.lua,sha256=QR9zhbilUJ6AZpiHlf9X_nLsHVtKlBIb95o2UxrPF_4,6844
+ar2md/cli.py,sha256=hns0amP7pDIbUF4Ytfa9lFiRqBcB-Xzmoi2TkCck_FU,12273
+ar2md-0.1.0.dist-info/METADATA,sha256=Xtf5SQczIzoaoe5zH52QY50-RNVPO8Ue4GX9dBJ-E94,5427
+ar2md-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+ar2md-0.1.0.dist-info/entry_points.txt,sha256=XEYdoLssJscmaljoga_jp6hJh3rFvHskNa-6qqKZQV8,41
+ar2md-0.1.0.dist-info/licenses/LICENSE,sha256=WvkD_s0T9J_on1SO6LvImJe3ZwDYHZtoBop-feLusac,1065
+ar2md-0.1.0.dist-info/RECORD,,

ar2md-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ar2md-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ar2md = ar2md.cli:main

ar2md-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cs-giung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.