mdfetch 0.1.0__tar.gz → 0.2.0__tar.gz

mdfetch-0.2.0/.specify/feature.json

@@ -0,0 +1,3 @@
+{
+  "feature_directory": "specs/002-devto-provider"
+}

{mdfetch-0.1.0 → mdfetch-0.2.0}/.specify/memory/changelog.md

@@ -2,6 +2,33 @@
 
 ---
 
+### mdfetch — dev.to Extractor — 2026-05-14
+
+**Branch**: `002-devto-provider`
+**Spec**: specs/002-devto-provider
+
+**What was added**:
+- `DevToExtractor` provider for `dev.to` articles, auto-discovered via `@register` decorator
+- Article body isolation from `<div id="article-body">` with cover image extracted from `<header class="crayons-article__header">` and prepended to output
+- `<iframe>` and liquid-tag embed (`ltag__*`) replacement with plain Markdown links (FR-019)
+- `UnsupportedContentTypeError` raised for non-article dev.to pages (profiles, tag listings)
+- 17 new unit tests in `tests/unit/test_devto_extractor.py`
+- 3 dev.to integration tests in `tests/integration/test_devto_integration.py` with snapshot golden files
+- Library version bumped from `0.1.0` to `0.2.0`
+- `"dev.to"` added to `pyproject.toml` keywords (T013)
+
+**New Components**:
+- `src/mdfetch/providers/devto.py` — DevToExtractor
+- `tests/unit/test_devto_extractor.py` — 17 unit tests
+- `tests/integration/test_devto_integration.py` — 3 integration tests
+- `tests/integration/snapshots/devto-integration-digest-december-2025.md`
+- `tests/integration/snapshots/devto-integration-digest-july-2025.md`
+- `tests/integration/snapshots/devto-integration-digest-march-2026.md`
+
+**Tasks Completed**: 13/13
+
+---
+
 ### mdfetch — Medium Extractor (Initial Release) — 2026-05-14
 
 **Branch**: `feature/first-draft`

{mdfetch-0.1.0 → mdfetch-0.2.0}/.specify/memory/plan.md

@@ -1,7 +1,7 @@
 # mdfetch — Main Implementation Plan
 
 **Last Updated**: 2026-05-14
-**Sources**: [specs/001-mdfetch-medium-extractor/plan.md]
+**Sources**: [specs/001-mdfetch-medium-extractor/plan.md], [specs/002-devto-provider/plan.md]
 
 ---
 
@@ -47,6 +47,13 @@ MediumExtractor(BaseExtractor)    — src/mdfetch/providers/medium.py
 ├── DOMAINS = frozenset({"medium.com"})
 ├── clean_html() → removes nav, clap buttons, sidebars, share elements, post-footer, author bio
 └── convert_to_markdown() → markdownify with ATX headings, fenced code blocks
+
+DevToExtractor(BaseExtractor)     — src/mdfetch/providers/devto.py
+├── DOMAINS = frozenset({"dev.to"})
+├── clean_html() → locates div#article-body; raises UnsupportedContentTypeError if absent;
+│                  replaces iframes and ltag embeds with anchor links; strips empty anchor-name
+│                  elements; prepends h1 + cover image from crayons-article__header
+└── convert_to_markdown() → markdownify with ATX headings; collapses 3+ newlines to 2
 ```
 
 ### Router / Auto-Discovery
@@ -82,20 +89,26 @@ src/
     ├── base.py              # BaseExtractor ABC + fetch_html() + extract() template
     └── providers/
         ├── __init__.py      # Empty — auto-discovery handles registration
-        └── medium.py        # MediumExtractor
+        ├── medium.py        # MediumExtractor
+        └── devto.py         # DevToExtractor [002-devto-provider]
 
 tests/
 ├── unit/
 │   ├── test_router.py
 │   ├── test_medium_extractor.py
 │   ├── test_fetch_errors.py
-│   └── test_silent.py
+│   ├── test_silent.py
+│   └── test_devto_extractor.py   # [002-devto-provider]
 └── integration/
     ├── snapshots/           # Golden Markdown files (article body snapshots)
     │   ├── from-drift-to-parity.md
     │   ├── architecting-the-asynchronous-agent.md
-    │   └── integration-digest-december-2025.md
-    └── test_medium_integration.py
+    │   ├── integration-digest-december-2025.md
+    │   ├── devto-integration-digest-december-2025.md   # [002-devto-provider]
+    │   ├── devto-integration-digest-july-2025.md       # [002-devto-provider]
+    │   └── devto-integration-digest-march-2026.md      # [002-devto-provider]
+    ├── test_medium_integration.py
+    └── test_devto_integration.py    # [002-devto-provider]
 
 specs/                       # Speckit feature specifications
 pyproject.toml               # hatchling build backend, uv package manager
@@ -118,14 +131,16 @@ Makefile                     # setup / test / integration / lint / typecheck / f
 
 ## Testing Strategy
 
-**Unit tests** (30 tests, offline):
+**Unit tests** (47 tests, offline):
 - Router: domain routing, subdomain suffix matching, duplicate registration, invalid URLs, unsupported platforms
 - MediumExtractor: clean_html, convert_to_markdown, empty content, non-article pages
+- DevToExtractor: clean_html (title/cover/heading/image preservation, iframe/ltag embed→link, anchor stripping, non-article error), convert_to_markdown (headings/code/lists/images, no raw HTML, empty content error) [002-devto-provider]
 - Fetch errors: HTTP 404, 503, timeout, connection error, size limit exceeded
 - Silent: no stdout/stderr output, no logging during extraction
 
-**Integration tests** (3 tests, network required):
+**Integration tests** (6 tests, network required):
 - Parametrized over 3 real stn1slv.medium.com articles
+- Parametrized over 3 real dev.to/stn1slv articles [002-devto-provider]
 - Snapshot-based containment check: `expected_body in extracted_result`
 - 3 retries with 2-second delay on `FetchError` (covers transient 403s/timeouts)
 - Run with: `make integration` or `uv run pytest tests/integration/ --override-ini=addopts=`
@@ -155,10 +170,14 @@ Makefile                     # setup / test / integration / lint / typecheck / f
 |----------|--------|-----------|
 | HTTP client | `httpx` (sync) | Supports async in v2 without swapping dependency |
 | HTML parser | `lxml` | Fast, tolerant; BeautifulSoup backend |
-| Article targeting | `<article>` element | Stable semantic HTML5; consistent across Medium versions |
+| Article targeting (Medium) | `<article>` element | Stable semantic HTML5; consistent across Medium versions |
+| Article targeting (dev.to) | `div#article-body` | dev.to does not use `<article>`; the id-scoped div already excludes all chrome | [002-devto-provider]
+| dev.to cover image | Extracted from `header.crayons-article__header`, prepended to body | Cover image is outside the article body div — must be fetched separately | [002-devto-provider]
+| dev.to embed handling | Replace `<iframe>` and `ltag__*` divs with anchor links | Embeds must not be silently dropped (FR-019); plain links are durable | [002-devto-provider]
 | Markdown converter | `markdownify` with ATX + `code_language=""` | Fenced code blocks, standard headings |
 | Routing | `pkgutil.iter_modules` auto-discovery + `@register` | SC-006: one new file = one new platform |
 | Integration tests | Snapshot containment + retry | Durable against minor HTML changes; resilient to transient 403s |
+| test_router.py domain example | Changed from `dev.to` to `substack.com` for "unsupported domain" test | Once DevToExtractor registers `dev.to`, those tests would no longer raise UnsupportedPlatformError | [002-devto-provider]
 
 ---
 

{mdfetch-0.1.0 → mdfetch-0.2.0}/.specify/memory/spec.md

@@ -1,13 +1,13 @@
 # mdfetch — Main Specification
 
 **Last Updated**: 2026-05-14
-**Sources**: [specs/001-mdfetch-medium-extractor/spec.md]
+**Sources**: [specs/001-mdfetch-medium-extractor/spec.md], [specs/002-devto-provider/spec.md]
 
 ---
 
 ## Overview
 
-`mdfetch` is a Python library that extracts article content from web platforms and returns it as clean, well-structured Markdown. The library enforces a provider pattern — an abstract base defines the extraction contract, and each supported platform is implemented as a separate, independent provider. The initial release supports `medium.com` and its subdomains only.
+`mdfetch` is a Python library that extracts article content from web platforms and returns it as clean, well-structured Markdown. The library enforces a provider pattern — an abstract base defines the extraction contract, and each supported platform is implemented as a separate, independent provider. Supported platforms: `medium.com` (and subdomains), `dev.to`.
 
 ---
 
@@ -48,6 +48,41 @@ A developer installs `mdfetch` from PyPI with `pip install mdfetch`, imports `ex
 
 ---
 
+### US-004 — Extract a dev.to Article to Markdown (P1)
+[Source: specs/002-devto-provider]
+
+A developer retrieves the readable content of a dev.to article as clean Markdown by calling the same single library function used for Medium — passing only the article URL, with no additional configuration. The library routes the request to the dev.to provider, fetches the page, isolates the article body, strips all non-content elements, and returns formatted Markdown.
+
+**Acceptance Scenarios**:
+1. Given a valid, publicly accessible dev.to article URL, when `extract(url)` is called, then it returns a non-empty Markdown string containing the article's title and at least one paragraph, with no raw HTML tags.
+2. Given a valid dev.to article URL, the returned Markdown contains no navigation menus, reaction buttons, comment sections, or author sidebar widgets.
+3. Given a dev.to article with headings, code blocks, and lists, the returned Markdown preserves those structural elements as proper Markdown equivalents (`#`, ` ``` `, `-`).
+
+---
+
+### US-005 — Receive Meaningful Errors for Non-Article dev.to Pages (P2)
+[Source: specs/002-devto-provider]
+
+A developer passing a dev.to URL that points to a profile page, a tag listing, or a podcast page receives a clear, typed error indicating the dev.to domain is recognised but the page type is not extractable.
+
+**Acceptance Scenarios**:
+1. Given a dev.to URL pointing to an author profile page, `extract()` raises `UnsupportedContentTypeError` (domain recognised, content type not extractable).
+2. Given a dev.to URL pointing to a tag listing page (e.g., `dev.to/t/kafka`), `extract()` raises `UnsupportedContentTypeError`.
+3. Given a URL from a domain other than dev.to, `extract()` raises `UnsupportedPlatformError` (unchanged from existing behaviour).
+
+---
+
+### US-006 — Integration Tests Pass Against Real dev.to Article URLs (P3)
+[Source: specs/002-devto-provider]
+
+A developer runs the integration test suite and all dev.to integration tests pass against three reference articles. The tests confirm title, structural elements, and absence of HTML tags on live content.
+
+**Acceptance Scenarios**:
+1. When integration tests for the three reference dev.to URLs execute with a stable internet connection, all three pass without errors or assertion failures.
+2. For each reference dev.to article, the extraction function returns non-empty Markdown free of HTML tags and containing recognisable content from the article.
+
+---
+
 ## Functional Requirements
 
 ### Extraction
@@ -70,7 +105,14 @@ A developer installs `mdfetch` from PyPI with `pip install mdfetch`, imports `ex
 
 ### Packaging & Testing
 - **FR-009**: The library MUST be packaged and distributed via PyPI using modern Python packaging best practices, enabling installation through the standard package manager without additional steps.
-- **FR-010**: The test suite MUST include integration tests that supply real Medium article URLs to the extraction function and assert that the output matches expected Markdown structure and content.
+- **FR-010**: The test suite MUST include integration tests that supply real article URLs (Medium and dev.to) to the extraction function and assert that the output matches expected Markdown structure and content.
+
+### dev.to Platform
+- **FR-015**: The library MUST add `dev.to` to the provider router so that any URL with the `dev.to` domain is dispatched to the dev.to provider without any change to the caller's code. [Source: specs/002-devto-provider]
+- **FR-016**: The library MUST include a dev.to provider that fetches the article page, isolates the main article body from `<div id="article-body">`, removes all non-content elements (navigation, social reaction widgets, comments, author sidebar, tag links), and returns the body as Markdown. [Source: specs/002-devto-provider]
+- **FR-017**: The dev.to provider MUST produce Markdown that preserves both the cover image (from the article header) and all inline body images as Markdown image syntax (`![alt](url)`). [Source: specs/002-devto-provider]
+- **FR-018**: The dev.to provider MUST raise `UnsupportedContentTypeError` when a `dev.to` URL is provided but the page is not an article (e.g., an author profile, a tag listing, or an organisation page). [Source: specs/002-devto-provider]
+- **FR-019**: The dev.to provider MUST replace embedded third-party content (GitHub Gists, CodePen demos, YouTube videos, liquid-tag embeds) with a plain Markdown link to the embedded resource URL. Embeds must not be silently dropped. [Source: specs/002-devto-provider]
 
 ---
 
@@ -89,9 +131,9 @@ A developer installs `mdfetch` from PyPI with `pip install mdfetch`, imports `ex
 ### Provider (Internal)
 | Attribute | Type | Description |
 |-----------|------|-------------|
-| `DOMAINS` | `frozenset[str]` | Domain suffixes this provider handles (e.g., `{"medium.com"}`) |
+| `DOMAINS` | `frozenset[str]` | Domain suffixes this provider handles (e.g., `{"medium.com"}`, `{"dev.to"}`) |
 
-**Invariants**: Each domain suffix registered to exactly one provider. Stateless — every call is independent.
+**Invariants**: Each domain suffix registered to exactly one provider. Stateless — every call is independent. Registered providers: `MediumExtractor` (medium.com), `DevToExtractor` (dev.to).
 
 ### ExtractionResult (Output)
 | Attribute | Type | Description |
@@ -150,6 +192,11 @@ caller provides URL string
 - **Oversized responses**: Responses exceeding 10 MB are rejected with `FetchError` to prevent OOM.
 - **Profile/tag pages**: When a `medium.com` URL points to a non-article page, `UnsupportedContentTypeError` is raised (distinct from `UnsupportedPlatformError`).
 - **HTTP 403 / transient failures**: Integration tests use a 3-retry helper with 2-second delay to handle transient rate limits.
+- **dev.to profile pages**: When a `dev.to` URL points to an author profile (no `div#article-body`), `UnsupportedContentTypeError` is raised.
+- **dev.to tag listing pages**: When a `dev.to` URL points to a tag page (e.g., `dev.to/t/kafka`), `UnsupportedContentTypeError` is raised.
+- **dev.to liquid-tag embeds**: Embedded third-party widgets (GitHub Gists, CodePen, YouTube) serialised as `<div class="ltag__*" data-url="...">` are replaced with plain Markdown links; they are never silently dropped.
+- **dev.to cover image**: The cover image lives in `<header class="crayons-article__header">`, not in `div#article-body` — the provider explicitly extracts and prepends it.
+- **dev.to HTML structure changes**: If `div#article-body` is absent, `UnsupportedContentTypeError` is raised.
 
 ---
 
@@ -161,6 +208,12 @@ caller provides URL string
 - **SC-004**: The returned Markdown for an article with headings, lists, and code blocks preserves all three structural element types in correct Markdown syntax.
 - **SC-005**: 100% of integration tests pass against a curated set of real Medium article URLs at the time of initial release.
 - **SC-006**: Adding support for a second platform requires creating exactly one new file (one new provider class decorated with `@register`). The router auto-discovers all provider modules at import time; no changes to shared library code are required.
+- **SC-007**: A developer already using the library for Medium can extract a dev.to article without any code change — only the URL changes. [Source: specs/002-devto-provider]
+- **SC-008**: The extraction function returns a result for a standard dev.to article in under 10 seconds on a stable internet connection. [Source: specs/002-devto-provider]
+- **SC-009**: The returned Markdown for any of the three reference dev.to articles contains no raw HTML tags (verified by automated assertion). [Source: specs/002-devto-provider]
+- **SC-010**: The returned Markdown for a dev.to article with headings, lists, and code blocks preserves all three structural element types in correct Markdown syntax. [Source: specs/002-devto-provider]
+- **SC-011**: 100% of integration tests pass against the three provided reference dev.to article URLs at the time of release. [Source: specs/002-devto-provider]
+- **SC-012**: The dev.to provider is delivered as exactly one new file; no existing source files are modified (except `test_router.py` for expected domain-example maintenance when the provider registers `dev.to`). [Source: specs/002-devto-provider]
 
 ---
 

{mdfetch-0.1.0 → mdfetch-0.2.0}/CLAUDE.md

@@ -45,6 +45,7 @@ uv run mypy src/               # type check
 
 ## Recent Changes
 
+- 002-devto-provider: dev.to article extraction provider — `DevToExtractor`, cover image + embed→link handling, 17 new unit tests, 3 integration tests, version 0.2.0
 - 001-mdfetch-medium-extractor: Initial library release — `extract()` API, Medium provider, typed exceptions, auto-discovery routing, PyPI packaging, snapshot integration tests
 
 <!-- SPECKIT START -->

{mdfetch-0.1.0 → mdfetch-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdfetch
-Version: 0.1.0
+Version: 0.2.0
 Summary: Extract article content from web platforms and return it as clean Markdown.
 Project-URL: Homepage, https://github.com/stn1slv/md-fetch
 Project-URL: Source, https://github.com/stn1slv/md-fetch
@@ -8,7 +8,7 @@ Project-URL: Issues, https://github.com/stn1slv/md-fetch/issues
 Author-email: Stanislav Deviatov <devyatov@gmail.com>
 License: MIT
 License-File: LICENSE
-Keywords: article,extraction,markdown,medium,scraping
+Keywords: article,dev.to,extraction,markdown,medium,scraping
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -44,7 +44,9 @@ pip install mdfetch
 ```python
 from mdfetch import extract
 
+# Works with any supported platform — just pass the URL
 markdown = extract("https://medium.com/some-publication/article-slug-abc123")
+markdown = extract("https://dev.to/username/article-slug")
 print(markdown)
 ```
 
@@ -84,6 +86,7 @@ except EmptyContentError as e:
 | Platform | Domains |
 |----------|---------|
 | Medium   | `medium.com`, `*.medium.com` |
+| dev.to   | `dev.to` |
 
 ## Development
 

{mdfetch-0.1.0 → mdfetch-0.2.0}/README.md

@@ -13,7 +13,9 @@ pip install mdfetch
 ```python
 from mdfetch import extract
 
+# Works with any supported platform — just pass the URL
 markdown = extract("https://medium.com/some-publication/article-slug-abc123")
+markdown = extract("https://dev.to/username/article-slug")
 print(markdown)
 ```
 
@@ -53,6 +55,7 @@ except EmptyContentError as e:
 | Platform | Domains |
 |----------|---------|
 | Medium   | `medium.com`, `*.medium.com` |
+| dev.to   | `dev.to` |
 
 ## Development
 

{mdfetch-0.1.0 → mdfetch-0.2.0}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mdfetch"
-version = "0.1.0"
+version = "0.2.0"
 description = "Extract article content from web platforms and return it as clean Markdown."
 readme = "README.md"
 license = { text = "MIT" }
 authors = [{ name = "Stanislav Deviatov", email = "devyatov@gmail.com" }]
-keywords = ["markdown", "scraping", "medium", "article", "extraction"]
+keywords = ["markdown", "scraping", "medium", "dev.to", "article", "extraction"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",

mdfetch-0.2.0/specs/002-devto-provider/checklists/requirements.md

@@ -0,0 +1,34 @@
+# Specification Quality Checklist: mdfetch — dev.to Extractor
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-05-14
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- All items pass. Specification is ready for `/speckit-plan`.

mdfetch-0.2.0/specs/002-devto-provider/contracts/public-api.md

@@ -0,0 +1,78 @@
+# Public API Contract: mdfetch — dev.to Extractor
+
+**Branch**: `002-devto-provider` | **Date**: 2026-05-14
+
+## Overview
+
+The dev.to extractor introduces no new public API surface. The existing `mdfetch.extract()` function is the sole entry point — callers use it identically for Medium and dev.to URLs.
+
+## `mdfetch.extract(url, *, retries=3, retry_delay=2.0) -> str`
+
+```python
+from mdfetch import extract
+
+markdown = extract("https://dev.to/stn1slv/integration-digest-for-december-2025-5dlp")
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `url` | `str` | required | Full URL of a dev.to article |
+| `retries` | `int` | `3` | Number of fetch attempts before raising |
+| `retry_delay` | `float` | `2.0` | Seconds between retry attempts |
+
+### Return value
+
+A `str` containing the article's content as Markdown. Structure:
+
+```markdown
+# Article Title
+
+![Cover image for Article Title](https://...)
+
+## Section Heading
+
+Paragraph text with [links](https://...).
+
+- List item
+- List item
+
+```python
+code block
+```
+
+[https://gist.github.com/...](https://gist.github.com/...)
+```
+
+### Exceptions
+
+All exceptions inherit from `mdfetch.MdfetchError` and carry `.url` and `.message` attributes.
+
+| Exception | When raised |
+|-----------|------------|
+| `InvalidURLError` | `url` is syntactically invalid |
+| `UnsupportedPlatformError` | Domain is not `dev.to` (or other registered domain) |
+| `UnsupportedContentTypeError` | `dev.to` URL is not an article (profile, tag, etc.) |
+| `FetchError` | Network error or timeout |
+| `HTTPStatusError` | Non-2xx HTTP response (adds `.status_code`) |
+| `EmptyContentError` | Article body found but contains no text |
+
+### Routing
+
+The router auto-discovers `DevToExtractor` at import time. No configuration required. Adding the provider file to `src/mdfetch/providers/devto.py` is sufficient for routing to work.
+
+## `DevToExtractor` (internal)
+
+Not part of the public API. Exposed only for testing via direct instantiation.
+
+```python
+from mdfetch.providers.devto import DevToExtractor
+
+extractor = DevToExtractor()
+html = extractor.fetch_html(url)
+from bs4 import BeautifulSoup
+soup = BeautifulSoup(html, "lxml")
+cleaned = extractor.clean_html(soup)
+markdown = extractor.convert_to_markdown(cleaned)
+```

mdfetch-0.2.0/specs/002-devto-provider/data-model.md

@@ -0,0 +1,55 @@
+# Data Model: mdfetch — dev.to Extractor
+
+**Branch**: `002-devto-provider` | **Date**: 2026-05-14
+
+## Entities
+
+This feature adds no new data structures. All entities are shared with the existing library model.
+
+### URL
+- **Representation**: Plain Python `str`
+- **Routing key**: `hostname` extracted via `urllib.parse.urlparse`; dev.to provider registers `"dev.to"` — the router's existing subdomain suffix matching handles `www.dev.to` automatically
+- **Validation**: Existing `InvalidURLError` raised by the router before the provider is invoked
+- **Accepted forms**:
+  - `https://dev.to/<username>/<article-slug>`  → article
+  - `https://dev.to/<username>` → profile → `UnsupportedContentTypeError`
+  - `https://dev.to/t/<tag>` → tag listing → `UnsupportedContentTypeError`
+
+### Provider
+- **New provider**: `DevToExtractor` implementing `BaseExtractor`
+- **DOMAINS**: `frozenset({"dev.to"})`
+- **Registered via**: `@register` decorator (auto-discovered by `_autodiscover_providers()`)
+- **File**: `src/mdfetch/providers/devto.py` (one new file; no existing files modified)
+
+### Extracted Article
+- **Output**: `str` — clean Markdown with ATX-style headings
+- **Content included**:
+  - Title (`# Title` from article `<h1>`)
+  - Cover image as `![alt](url)` (if present)
+  - Article body: paragraphs, headings, code blocks, inline code, lists, blockquotes
+  - Body images as `![alt](url)`
+  - Embedded resources (Gists, CodePens, YouTube) as plain Markdown links `[url](url)`
+- **Content excluded**:
+  - Author name, avatar, publication date
+  - Series navigation panels
+  - Article tags (`#kafka`, `#api`, etc.)
+  - Comments section
+  - Reaction buttons
+  - Advertisements
+
+## State Transitions
+
+None — extraction is a stateless, single-call operation with no persistent state.
+
+## Error Cases
+
+| Condition | Exception |
+|-----------|-----------|
+| URL has no `dev.to` domain | `UnsupportedPlatformError` (raised by router) |
+| URL is syntactically invalid | `InvalidURLError` (raised by router) |
+| HTTP request fails | `FetchError` |
+| Non-2xx HTTP response | `HTTPStatusError` |
+| `div#article-body` not found | `UnsupportedContentTypeError` |
+| Article body has no extractable text | `EmptyContentError` |
+
+All exception classes are defined in `mdfetch.exceptions` — no new classes needed.

mdfetch-0.2.0/specs/002-devto-provider/plan.md

@@ -0,0 +1,165 @@
+# Implementation Plan: mdfetch — dev.to Extractor
+
+**Branch**: `002-devto-provider` | **Date**: 2026-05-14 | **Spec**: [spec.md](spec.md)
+
+**Input**: Feature specification from `specs/002-devto-provider/spec.md`
+
+## Summary
+
+Add a `DevToExtractor` provider that fetches dev.to article pages, extracts the article body from `<div id="article-body">`, prepends the title and cover image from the page header, converts embedded resources to plain Markdown links, and returns clean Markdown. The provider is one new file; no shared library code is modified.
+
+## Technical Context
+
+**Language/Version**: Python 3.12+
+
+**Primary Dependencies**: `httpx` (HTTP fetch), `BeautifulSoup` / `lxml` (HTML parsing), `markdownify` (Markdown conversion), `pytest` (testing)
+
+**Storage**: N/A — stateless extraction library
+
+**Testing**: `pytest` — unit tests (no network) + integration tests (`-m integration`, real URLs)
+
+**Target Platform**: PyPI library (cross-platform)
+
+**Project Type**: library
+
+**Performance Goals**: Extraction in under 10 seconds per article on stable internet (SC-002)
+
+**Constraints**: One new provider file; no changes to existing shared code
+
+**Scale/Scope**: Single-article extraction per call; no volume concerns
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+- [x] Validates Provider Pattern Architecture — `DevToExtractor` inherits `BaseExtractor`; uses `@register`; one new file only; no shared code changes
+- [x] Confirms Technology Stack — `httpx`, `BeautifulSoup`, `markdownify`, `pytest` (all already in use; no new deps needed)
+- [x] Adheres to Coding Standards — strict type hints, PEP 8, clear English naming
+- [x] Incorporates Integration Testing — three reference dev.to URLs verified in `tests/integration/test_devto_integration.py`
+- [x] Respects Packaging and Distribution standards — `pyproject.toml` + `src/` layout unchanged; `uv` for all dev commands
+
+All constitution gates pass. No violations to justify.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/002-devto-provider/
+├── plan.md              # This file
+├── research.md          # Phase 0 output — dev.to HTML structure analysis
+├── data-model.md        # Phase 1 output — entities and error cases
+├── quickstart.md        # Phase 1 output — usage examples
+├── contracts/
+│   └── public-api.md    # Phase 1 output — API contract (unchanged from Medium)
+└── tasks.md             # Phase 2 output (/speckit-tasks — not created here)
+```
+
+### Source Code Changes
+
+```text
+src/mdfetch/providers/
+├── __init__.py          # UNCHANGED — auto-discovery handles new file
+└── devto.py             # NEW — DevToExtractor (single new file)
+
+tests/unit/
+└── test_devto_extractor.py   # NEW — unit tests (no network)
+
+tests/integration/
+├── snapshots/
+│   ├── devto-integration-digest-december-2025.md   # NEW — snapshot
+│   ├── devto-integration-digest-july-2025.md        # NEW — snapshot
+│   └── devto-integration-digest-march-2026.md       # NEW — snapshot
+└── test_devto_integration.py   # NEW — integration tests (real URLs)
+```
+
+No existing library source files are modified (`src/mdfetch/` unchanged).
+
+**Side effect documented**: `tests/unit/test_router.py` required a one-line update — its "unsupported domain" example used `dev.to`, which became a supported domain once this provider was registered. The two test cases were updated to use `substack.com` instead. This is an expected consequence of any new provider registration.
+
+**Version**: Library version bumped from `0.1.0` to `0.2.0` in `pyproject.toml` at time of release.
+
+## Implementation Specification
+
+### `src/mdfetch/providers/devto.py`
+
+```python
+@register
+class DevToExtractor(BaseExtractor):
+    DOMAINS: frozenset[str] = frozenset({"dev.to"})
+
+    def clean_html(self, soup: BeautifulSoup) -> Tag:
+        # 1. Locate article body — absence means non-article page
+        body = soup.find("div", id="article-body")
+        if not isinstance(body, Tag):
+            raise UnsupportedContentTypeError(...)
+
+        # 2. Handle embedded content: replace iframes with anchor links
+        for iframe in body.find_all("iframe"):
+            src = iframe.get("src") or iframe.get("data-src") or ""
+            link = soup.new_tag("a", href=src)
+            link.string = src
+            iframe.replace_with(link)
+
+        # 3. Handle liquid tag embeds (class containing "ltag")
+        for embed in body.find_all(class_=re.compile(r"ltag", re.I)):
+            src = embed.get("data-src") or embed.get("src") or str(embed.get("data-url", ""))
+            if src:
+                link = soup.new_tag("a", href=src)
+                link.string = src
+                embed.replace_with(link)
+            else:
+                embed.decompose()
+
+        # 4. Strip empty anchor-name links inserted before headings
+        for anchor in body.find_all("a", attrs={"name": True}):
+            if not anchor.get_text(strip=True):
+                anchor.decompose()
+
+        # 5. Extract title and cover image from header; prepend to body
+        header = soup.find("header", class_="crayons-article__header")
+        if header:
+            h1 = header.find("h1")
+            cover_img = header.find("img", class_="crayons-article__cover__image")
+            if h1:
+                body.insert(0, h1)       # prepend <h1> as first child of body
+            if cover_img:
+                body.insert(1, cover_img) # prepend cover image after title
+
+        return body
+
+    def convert_to_markdown(self, tag: Tag) -> str:
+        md = markdownify(str(tag), heading_style="ATX", code_language="", strip=["script", "style"])
+        md = md.strip()
+        md = re.sub(r"\n{3,}", "\n\n", md)
+        if not md:
+            raise EmptyContentError(...)
+        return md
+```
+
+### `tests/unit/test_devto_extractor.py`
+
+Unit tests cover (no network):
+- `clean_html` raises `UnsupportedContentTypeError` when `div#article-body` absent
+- `clean_html` raises `UnsupportedContentTypeError` for profile-page HTML (no article-body)
+- `clean_html` preserves `<h1>` title and cover image
+- `clean_html` replaces `<iframe>` with anchor link
+- `clean_html` strips empty anchor-name links
+- `convert_to_markdown` produces ATX headings, code blocks, lists
+- `convert_to_markdown` raises `EmptyContentError` on blank body
+- No raw HTML tags in converted Markdown
+
+### `tests/integration/test_devto_integration.py`
+
+Integration tests mirror the Medium pattern:
+- Parametrized over 3 reference URLs + snapshot filenames
+- `@pytest.mark.integration` marker
+- Snapshot containment check: `expected in result`
+- Snapshots generated by running extraction once and saving output
+
+## Complexity Tracking
+
+*No constitution violations — section left intentionally blank.*
+
+### Revision: Implementation Sync 2026-05-14
+- Reason: Documented two implementation side-effects not captured in the original plan: (1) `tests/unit/test_router.py` required domain-example update when dev.to became a registered provider; (2) library version bumped from 0.1.0 to 0.2.0 at release. `pyproject.toml` keywords gap (missing "dev.to") tracked as T013.