medium2md-cli 0.1.0__py3-none-any.whl

medium2md/cli.py

@@ -0,0 +1,102 @@
+import zipfile
+from pathlib import Path
+import tempfile
+import typer
+
+from medium2md.pipeline import (
+    find_post_html_files,
+    get_title_canonical,
+    convert_html_file,
+    slug_from_post,
+    write_bundle,
+)
+
+app = typer.Typer(help="Convert a Medium export ZIP into Hugo page bundles.")
+
+
+@app.command()
+def convert(
+    export_zip: Path = typer.Argument(..., exists=True, file_okay=True, dir_okay=False),
+    out: Path = typer.Option(Path("content/posts"), "--out", "-o"),
+):
+    out = out.resolve()
+    if not out.exists():
+        if not typer.confirm(
+            f"Output directory does not exist: {out}\nCreate it?",
+            default=True,
+        ):
+            raise typer.Exit(1)
+        out.mkdir(parents=True, exist_ok=True)
+        typer.echo(f"Created {out}")
+    elif not out.is_dir():
+        typer.echo(f"Error: Output path is not a directory: {out}", err=True)
+        raise typer.Exit(1)
+
+    typer.echo(f"Export: {export_zip}")
+    typer.echo(f"Out:    {out}")
+
+    with tempfile.TemporaryDirectory(prefix="medium2md_") as td:
+        tmp_dir = Path(td)
+
+        with zipfile.ZipFile(export_zip, "r") as z:
+            z.extractall(tmp_dir)
+
+        all_html = sorted(tmp_dir.rglob("*.html"))
+        post_files = find_post_html_files(tmp_dir)
+
+        typer.echo(f"Found {len(all_html)} HTML file(s) in export, {len(post_files)} post(s) to convert.")
+
+        if not post_files:
+            typer.echo(
+                typer.style(
+                    "Warning: No post HTML files found. "
+                    "Expected posts under a 'posts/' folder in the export, or excluded README/blocks/bookmarks/claps/highlights/interests.",
+                    fg="yellow",
+                ),
+                err=True,
+            )
+            raise typer.Exit(1)
+
+        used_slugs: set[str] = set()
+        written = 0
+        errors = 0
+
+        for i, html_path in enumerate(post_files, 1):
+            rel = html_path.relative_to(tmp_dir)
+            try:
+                title, canonical = get_title_canonical(html_path)
+                slug = slug_from_post(title, canonical)
+                base_slug = slug
+                while slug in used_slugs:
+                    # Simple collision: append -2, -3, ...
+                    suffix = 2 if slug == base_slug else int(slug.split("-")[-1]) + 1
+                    slug = f"{base_slug}-{suffix}"
+                used_slugs.add(slug)
+                bundle_dir = out / slug
+                bundle_dir.mkdir(parents=True, exist_ok=True)
+                title, canonical, body_md, num_images = convert_html_file(html_path, tmp_dir, bundle_dir)
+                write_bundle(out, slug, title, canonical, body_md)
+                written += 1
+                img_info = f" ({num_images} image(s))" if num_images else ""
+                typer.echo(f"  [{i}/{len(post_files)}] {slug}  →  {out / slug / 'index.md'}{img_info}")
+            except Exception as e:
+                errors += 1
+                typer.echo(
+                    typer.style(f"  [{i}/{len(post_files)}] Failed {rel}: {e}", fg="red"),
+                    err=True,
+                )
+
+        typer.echo("")
+        if written:
+            typer.echo(typer.style(f"Done. {written} post(s) written to {out}", fg="green"))
+        if errors:
+            typer.echo(typer.style(f"Failed: {errors} post(s) could not be converted.", fg="red"), err=True)
+        if written == 0:
+            typer.echo(
+                typer.style(
+                    "No posts were written. Check errors above or export structure (expected 'posts/' folder).",
+                    fg="yellow",
+                ),
+                err=True,
+            )
+            raise typer.Exit(1)

medium2md/main.py

@@ -0,0 +1,6 @@
+def main():
+    print("Hello from medium2md!")
+
+
+if __name__ == "__main__":
+    main()

medium2md/pipeline.py

@@ -0,0 +1,229 @@
+"""Minimal conversion pipeline: find post HTML, parse, convert to Markdown, write Hugo bundles."""
+
+import shutil
+import time
+from pathlib import Path
+from urllib.parse import urlparse
+
+import yaml
+from bs4 import BeautifulSoup
+from markdownify import markdownify as md
+from slugify import slugify
+
+try:
+    import httpx
+except ImportError:
+    httpx = None  # type: ignore[assignment]
+
+# Request like a browser so Medium's CDN serves images
+IMAGE_REQUEST_HEADERS = {
+    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; rv:109.0) Gecko/20100101 Firefox/119.0",
+    "Accept": "image/avif,image/webp,image/png,image/svg+xml,image/*,*/*;q=0.8",
+}
+
+
+# Non-post directories in Medium export (utility pages)
+NON_POST_DIRS = {"blocks", "bookmarks", "claps", "highlights", "interests"}
+
+
+def find_post_html_files(root: Path) -> list[Path]:
+    """Return HTML files that are likely Medium posts.
+
+    Prefer files under root/posts/ if that directory exists (standard export layout).
+    Otherwise exclude known non-post directories and return the rest.
+    """
+    posts_dir = root / "posts"
+    if posts_dir.is_dir():
+        return sorted(posts_dir.rglob("*.html"))
+    # No posts/ folder: exclude known utility dirs
+    all_html = sorted(p for p in root.rglob("*.html") if p.is_file())
+    return [
+        p
+        for p in all_html
+        if not any(part in p.parts for part in NON_POST_DIRS)
+        and p.name != "README.html"
+    ]
+
+
+def _extract_canonical(soup: BeautifulSoup) -> str | None:
+    link = soup.find("link", rel="canonical", href=True)
+    return link["href"].strip() if link else None
+
+
+def _extract_title(soup: BeautifulSoup) -> str:
+    h1 = soup.find("h1")
+    if h1:
+        return h1.get_text(strip=True)
+    title_el = soup.find("title")
+    if title_el:
+        return title_el.get_text(strip=True)
+    return "Untitled"
+
+
+def _extract_article_html(soup: BeautifulSoup) -> str:
+    """Extract main article content as HTML string."""
+    article = soup.find("article")
+    if article:
+        return str(article)
+    # Fallback: first main or content-heavy section
+    main = soup.find("main")
+    if main:
+        return str(main)
+    # Last resort: body
+    body = soup.find("body")
+    return str(body) if body else ""
+
+
+def get_title_canonical(html_path: Path) -> tuple[str, str | None]:
+    """Light parse to get title and canonical URL only (for slug + bundle dir)."""
+    raw = html_path.read_text(encoding="utf-8", errors="replace")
+    soup = BeautifulSoup(raw, "lxml")
+    return _extract_title(soup), _extract_canonical(soup)
+
+
+# Extension from URL path or Content-Type
+_CT_EXT = {
+    "image/jpeg": ".jpg",
+    "image/jpg": ".jpg",
+    "image/png": ".png",
+    "image/gif": ".gif",
+    "image/webp": ".webp",
+    "image/svg+xml": ".svg",
+}
+
+
+def _extension_for_url(url: str, content_type: str | None = None) -> str:
+    if content_type and content_type.split(";")[0].strip().lower() in _CT_EXT:
+        return _CT_EXT[content_type.split(";")[0].strip().lower()]
+    path = urlparse(url).path
+    if path and "." in path:
+        ext = path.rsplit(".", 1)[-1].lower()
+        if ext in ("png", "jpg", "jpeg", "gif", "webp", "svg"):
+            return f".{ext}"
+    return ".png"
+
+
+def _localize_images(
+    article_soup: BeautifulSoup,
+    html_path: Path,
+    tmp_dir: Path,
+    bundle_dir: Path,
+) -> int:
+    """In-place: resolve each img src to a local file or download, copy into bundle/images/, set src to images/<name>. Returns count of images localized."""
+    images_dir = bundle_dir / "images"
+    images_dir.mkdir(parents=True, exist_ok=True)
+    imgs = article_soup.find_all("img", src=True)
+    localized = 0
+    for i, img in enumerate(imgs, 1):
+        src = img["src"].strip()
+        if not src:
+            continue
+        # Relative or file path: resolve against the HTML file's directory
+        if not src.startswith(("http://", "https://")):
+            resolved = (html_path.parent / src).resolve()
+            try:
+                resolved.relative_to(tmp_dir)
+            except ValueError:
+                continue  # outside export, skip
+            if not resolved.is_file():
+                continue
+            ext = resolved.suffix.lower() or ".png"
+            dest_name = f"{i}{ext}"
+            dest = images_dir / dest_name
+            shutil.copy2(resolved, dest)
+            img["src"] = f"images/{dest_name}"
+            localized += 1
+            continue
+        # Remote URL: download (with User-Agent and retry so CDNs don't block)
+        if not httpx:
+            continue
+        last_error: Exception | None = None
+        for attempt in range(2):
+            try:
+                r = httpx.get(
+                    src,
+                    follow_redirects=True,
+                    timeout=45,
+                    headers=IMAGE_REQUEST_HEADERS,
+                )
+                r.raise_for_status()
+                if len(r.content) == 0:
+                    raise ValueError("empty response")
+                ct = r.headers.get("content-type", "")
+                ext = _extension_for_url(src, ct)
+                dest_name = f"{i}{ext}"
+                dest = images_dir / dest_name
+                dest.write_bytes(r.content)
+                img["src"] = f"images/{dest_name}"
+                localized += 1
+                last_error = None
+                break
+            except Exception as e:
+                last_error = e
+                if attempt < 1:
+                    time.sleep(0.5 + attempt)
+        if last_error is not None:
+            # Leave src unchanged so the MD still has the URL; user can fix manually
+            pass
+    return localized
+
+
+def convert_html_file(
+    html_path: Path,
+    tmp_dir: Path,
+    bundle_dir: Path,
+) -> tuple[str, str | None, str, int]:
+    """Parse one post HTML file, localize images into bundle_dir/images/, return (title, canonical_url, markdown_body, num_images_localized)."""
+    raw = html_path.read_text(encoding="utf-8", errors="replace")
+    soup = BeautifulSoup(raw, "lxml")
+    title = _extract_title(soup)
+    canonical = _extract_canonical(soup)
+    article_html = _extract_article_html(soup)
+    if not article_html:
+        body_md = ""
+        localized = 0
+    else:
+        article_soup = BeautifulSoup(article_html, "lxml")
+        localized = _localize_images(article_soup, html_path, tmp_dir, bundle_dir)
+        body_md = md(
+            str(article_soup),
+            heading_style="ATX",
+            strip=["script", "style"],
+            escape_asterisks=False,
+            escape_underscores=False,
+        )
+    return title, canonical, (body_md or "").strip(), localized
+
+
+def slug_from_post(title: str, canonical: str | None) -> str:
+    """Generate a Hugo-friendly slug."""
+    if canonical and "/" in canonical:
+        # e.g. https://medium.com/@user/some-post-slug-123
+        part = canonical.rstrip("/").split("/")[-1]
+        if part and part != "medium.com":
+            s = slugify(part, max_length=80)
+            if s:
+                return s
+    return slugify(title, max_length=80) or "untitled"
+
+
+def write_bundle(out_root: Path, slug: str, title: str, canonical: str | None, body_md: str) -> Path:
+    """Write one Hugo page bundle: out_root/<slug>/index.md. Returns path to index.md."""
+    bundle_dir = out_root / slug
+    bundle_dir.mkdir(parents=True, exist_ok=True)
+    front = {
+        "title": title,
+        "draft": True,
+        "slug": slug,
+    }
+    if canonical:
+        front["medium"] = {"canonical": canonical}
+    index_md = bundle_dir / "index.md"
+    with index_md.open("w", encoding="utf-8") as f:
+        f.write("---\n")
+        f.write(yaml.dump(front, default_flow_style=False, allow_unicode=True, sort_keys=False))
+        f.write("---\n\n")
+        f.write(body_md)
+        if body_md and not body_md.endswith("\n"):
+            f.write("\n")
+    return index_md

medium2md_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: medium2md-cli
+Version: 0.1.0
+Summary: Convert a Medium export ZIP into Hugo-ready Markdown page bundles with localized images.
+Project-URL: Homepage, https://github.com/edgarbc/medium2md
+Project-URL: Repository, https://github.com/edgarbc/medium2md
+Project-URL: Documentation, https://github.com/edgarbc/medium2md#readme
+Author: Edgar Bermudez
+License: MIT
+License-File: LICENSE
+Keywords: export,hugo,markdown,medium,migration,static-site
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.13
+Requires-Dist: beautifulsoup4>=4.14.3
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: lxml>=6.0.2
+Requires-Dist: markdownify>=1.2.2
+Requires-Dist: python-dateutil>=2.9.0.post0
+Requires-Dist: python-slugify>=8.0.4
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=14.3.3
+Requires-Dist: typer>=0.24.1
+Provides-Extra: dev
+Requires-Dist: twine>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# medium2md
+
+[![PyPI version](https://img.shields.io/pypi/v/medium2md-cli.svg)](https://pypi.org/project/medium2md-cli/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/medium2md-cli.svg)](https://pypi.org/project/medium2md-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> Convert a Medium export ZIP into clean, Hugo-ready Markdown page bundles.
+
+**medium2md** is a CLI tool that transforms Medium's HTML export into properly structured [Hugo](https://gohugo.io/) content using page bundles — enabling full ownership of your content and a clean, reproducible migration from Medium to Hugo.
+
+---
+
+## Table of Contents
+
+- [Why This Exists](#why-this-exists)
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Output Structure](#output-structure)
+- [Project Structure](#project-structure)
+- [Development Roadmap](#development-roadmap)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Why This Exists
+
+Medium allows you to export your account data as a ZIP archive, but the raw export:
+
+- Contains unstructured HTML
+- Includes inconsistent metadata
+- References remote image URLs
+
+**medium2md** solves this by providing:
+
+| Feature | Description |
+|---|---|
+| HTML → Markdown | Converts Medium HTML posts to clean Markdown |
+| Hugo front matter | Generates YAML front matter from post metadata |
+| Image localization | Downloads remote images into each bundle; copies local images when present in the export |
+| Canonical URL | Preserves the original Medium URL |
+| Conversion reports | Summarizes what was converted and what was skipped |
+| Incremental re-runs | *(planned)* Re-run only changed posts |
+
+This tool is designed to be **deterministic**, **reproducible**, and **CI-friendly**.
+
+---
+
+## Features
+
+### MVP (current)
+
+- Convert Medium export ZIP (posts under `posts/` in the export)
+- Extract title and canonical URL; generate slug
+- Convert HTML to Markdown
+- Create Hugo page bundles with `index.md` and optional `images/`
+- Image localization: download remote images into the bundle; copy local images when present in the export
+- Basic slug collision handling (`slug-2`, `slug-3`, …)
+- Terminal progress and summary; per-post image count; prompt to create missing output dir
+
+### Planned
+
+- Extract date and optional metadata (tags, etc.) into front matter
+- Incremental runs via state file
+- Embed detection and shortcode conversion (YouTube, Twitter, Gist)
+- Pandoc backend option
+- Verification command
+- Theme-specific front matter mapping
+- Conversion report (e.g. JSON/file)
+
+---
+
+## Installation
+
+This project uses [uv](https://github.com/astral-sh/uv) for dependency management.
+
+```bash
+git clone https://github.com/edgarbc/medium2md.git
+cd medium2md
+uv sync
+```
+
+Once published to PyPI, install with:
+
+```bash
+pip install medium2md-cli
+# or with uv:
+uv tool install medium2md-cli
+```
+
+The CLI command is still `medium2md`.
+
+---
+
+## Usage
+
+Copy your Medium export ZIP into the `input/` directory (already set up and git-ignored):
+
+```bash
+cp ~/Downloads/medium-export.zip input/
+uv run medium2md input/medium-export.zip --out ../blog/content/posts
+```
+
+> **Note:** The `input/` directory is tracked by git (via `.gitkeep`) so it exists after a fresh clone, but its contents are ignored — your ZIP files will never be accidentally committed.
+
+### Front Matter Example
+
+Each converted post produces an `index.md` with Hugo-compatible YAML front matter. Current output:
+
+```yaml
+---
+title: "My Post Title"
+draft: true
+slug: "my-post-slug"
+medium:
+  canonical: "https://medium.com/@you/post-slug"
+---
+```
+
+Additional keys (e.g. `date`, `lastmod`, `tags`) are planned.
+
+---
+
+## Output Structure
+
+Each Medium post becomes a Hugo page bundle. Image links in the Markdown point into the bundle’s `images/` folder (remote images are downloaded; local images from the export are copied):
+
+```
+content/posts/
+└── my-post-slug/
+    ├── index.md
+    └── images/
+        ├── 1.png
+        ├── 2.jpg
+        └── …
+```
+
+---
+
+## Project Structure
+
+```
+medium2md/
+├── medium2md/
+│   ├── __init__.py
+│   ├── cli.py
+│   ├── pipeline.py
+│   └── main.py
+├── pyproject.toml
+├── README.md
+├── project-plan.md
+└── input/
+    └── medium-export.zip
+```
+
+### Pipeline Architecture
+
+medium2md follows a layered pipeline:
+
+```
+ZIP → extract → find posts → parse HTML → localize images (copy/download) → Markdown conversion → front matter + Hugo bundle write
+```
+
+> **Philosophy:** Correctness first, cleverness later.
+
+---
+
+## Development Roadmap
+
+| Milestone | Focus | Status |
+|---|---|---|
+| 1 — MVP | ZIP ingestion, HTML→Markdown, Hugo bundle writing, image localization | ✅ Done |
+| 2 — Robustness | Incremental state tracking, metadata fallback, verify command | 📋 Planned |
+| 3 — Polish | Embed conversion, theme config mapping, Pandoc backend, internal link rewriting | 📋 Planned |
+
+---
+
+## Contributing
+
+Contributions are welcome! To get started:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feat/my-feature`)
+3. Make your changes
+4. Open a pull request (run `uv run medium2md --help` to confirm the CLI works)
+
+---
+
+## Publishing to PyPI (maintainers)
+
+1. Bump `version` in `pyproject.toml`.
+2. Build: `uv build` (creates `dist/`).
+3. Install dev deps and upload: `uv sync --extra dev` then `uv run twine upload dist/*` (requires a [PyPI API token](https://pypi.org/help/#apitoken); use `__token__` as username).
+4. Optionally tag the release: `git tag v0.1.0 && git push --tags`.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).
+
+---
+
+> Built by [Edgar Bermudez](https://github.com/edgarbc) and [GitHub Copilot](https://github.com/features/copilot) with 💖 to enable long-term content ownership and reproducible publishing workflows.
+>
+> Not affiliated with Medium or any of its subsidiaries.

medium2md_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+medium2md/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+medium2md/cli.py,sha256=B22AXFzgL7lSZv1NCMmyYQewe0gWkqeYpRyzV2aoDlQ,3711
+medium2md/main.py,sha256=8Yg-1EqgELUgB_nTPV4TZYm5ZjFkdiIjfm0UlJluc7Y,87
+medium2md/pipeline.py,sha256=qpVA9wJ3rlOxq1e_nUcEBmb04IAteLXJgBsp_SK_AAE,7875
+medium2md_cli-0.1.0.dist-info/METADATA,sha256=PxztbcnfLwld8xQUCLnUP9FBBsZKVLKIZM97rD9L7QE,7215
+medium2md_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+medium2md_cli-0.1.0.dist-info/entry_points.txt,sha256=RZBS8UcYhjELVwc0XTwboCZIPMcI5uH8rYxTpQ8mswQ,48
+medium2md_cli-0.1.0.dist-info/licenses/LICENSE,sha256=sIy7BqZo1LLk4ZVHX15j86tqhU4CihZHu-FKdyLWZyA,1071
+medium2md_cli-0.1.0.dist-info/RECORD,,

medium2md_cli-0.1.0.dist-info/WHEEL

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

medium2md_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+medium2md = medium2md.cli:app

medium2md_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edgar Bermudez
+
+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.