Last indexed: 7 March 2026 (2980e3)

Dev.to Adapter

This page documents the DevTo_Adapter class, which prepares WordPress post content for submission to the Dev.to (Forem) platform via its API. Unlike the file-based Hugo and Astro adapters, DevTo_Adapter produces no files on disk — it generates a Markdown string with YAML front matter that is passed directly to the DevTo_API client.

For the API client that transmits this content, see Dev.to API Client. For the interface contract that DevTo_Adapter fulfills, see Adapter Interface. For how the adapter is selected and invoked inside the sync pipeline, see Sync Runner.

Role in the Architecture

DevTo_Adapter sits between the WordPress data model and the Dev.to HTTP API. It is responsible for shaping post data into what Dev.to expects, but does not handle any network communication.

Class diagram: DevTo_Adapter in context

Sources: adapters/class-devto-adapter.php27-498

State: Instance Properties

DevTo_Adapter holds two mutable properties that must be configured before calling convert(). Both are set by the Sync_Runner after it inspects the post's current Dev.to state.

Property	Type	Default	Set by
`$canonical_url`	`string\|null`	`null`	`set_canonical_url()`
`$published`	`bool\|null`	`false`	`set_published_status()`

Sources: adapters/class-devto-adapter.php34-41

`set_canonical_url()`

adapters/class-devto-adapter.php48-50

Stores a URL that will be included as the canonical_url front matter field. This supports cross-posting workflows where the WordPress site is the canonical source.

`set_published_status()`

adapters/class-devto-adapter.php64-70

Stores the article's current published state on Dev.to. The semantics of the three possible values are important:

Value	Meaning	Effect on front matter
`false`	New article or explicitly draft	`published: false` included
`true`	Article is live on Dev.to	`published: true` included
`null`	Status unknown	`published` key omitted entirely

Omitting published when the state is unknown prevents accidental publish/unpublish actions during an update. See adapters/class-devto-adapter.php121-127

Content Conversion Pipeline

Flow: convert() to final Markdown string

Sources: adapters/class-devto-adapter.php84-89 adapters/class-devto-adapter.php293-301

Note: The $image_mapping and $featured_image_path parameters accepted by convert() are not used. Dev.to fetches images from absolute URLs, so no local file mapping is needed.

Front Matter Fields

get_front_matter() returns an associative array. These fields are then serialized to YAML by build_markdown().

Diagram: front matter field sources

Sources: adapters/class-devto-adapter.php114-149

Field Reference

Front Matter Key	Source	Condition
`title`	`post->post_title`	Always included
`description`	excerpt or truncated content	Always included
`tags`	WordPress post tags	Always included (may be empty array)
`published`	`$this->published`	Omitted when `null`
`cover_image`	Featured image (absolute URL)	Omitted when no featured image
`canonical_url`	`$this->canonical_url`	Omitted when not set
`series`	Primary WordPress category name	Omitted when no categories

Sources: adapters/class-devto-adapter.php114-149

Tag Formatting Rules

Dev.to enforces strict tag constraints. The private get_tags() method applies these rules in sequence:

Fetch tag names via wp_get_post_tags() with fields => names.
Convert each tag to lowercase with strtolower().
Replace spaces with hyphens using str_replace(' ', '-', $tag).
Strip all characters except a-z, 0-9, and - using preg_replace('/[^a-z0-9\-]/', '', $tag).
Truncate the array to a maximum of 4 tags via array_slice($formatted, 0, 4).

Sources: adapters/class-devto-adapter.php193-214

Examples:

WordPress Tag	After Formatting
`Open Source`	`open-source`
`C++`	`c`
`PHP 8.1`	`php-81`
`Web Dev`	`web-dev`

Description Generation

get_description() produces a string of at most 160 characters:

If post_excerpt is non-empty, use it directly.
Otherwise, strip all HTML tags from post_content and take the first 25 words via wp_trim_words().
If the result exceeds 160 characters, truncate to 157 characters and append ....

Sources: adapters/class-devto-adapter.php161-178

Cover Image Handling

get_cover_image() retrieves the post's featured image as an absolute URL. Dev.to fetches the image directly from the URL, so a relative path would fail.

Steps:

Call get_post_thumbnail_id().
Retrieve the URL with wp_get_attachment_url().
If the URL has no scheme, prefix it with home_url().
Validate that the scheme is http or https; return null otherwise.

The recommended image ratio for Dev.to cover images is 100:42 (e.g., 1000×420 px).

Sources: adapters/class-devto-adapter.php228-254

HTML-to-Markdown Conversion

html_to_markdown() performs a regex-based conversion. It does not use a library (unlike the Hugo/Astro adapters). The conversion sequence is:

Input HTML	Output Markdown
WordPress block comments	Stripped (inner content kept)
`<img src="..." alt="...">`	`!<FileRef file-url="https://github.com/pcescato/ajc-bridge/blob/2980e3ea/alt" undefined file-path="alt">Hii</FileRef>`
`<a href="...">text</a>`	`<FileRef file-url="https://github.com/pcescato/ajc-bridge/blob/2980e3ea/text" undefined file-path="text">Hii</FileRef>`
`<strong>`, `<b>`	`text`
`<em>`, `<i>`	`text`
`<h1>` … `<h6>`	`#` … `######`
`<li>`	`- item`
`<pre><code>`	``` ``` fenced block
`<code>`	`inline`
`<blockquote>`	`> line` per line
`<p>`	Double newline
`<br>` variants	Single newline
Remaining tags	Stripped with `wp_strip_all_tags()`

After conversion, consecutive blank lines are collapsed to a single blank line.

Sources: adapters/class-devto-adapter.php313-400

Absolute Image URL Enforcement

After HTML-to-Markdown conversion, ensure_absolute_image_urls() scans the Markdown for image references matching !<FileRef file-url="https://github.com/pcescato/ajc-bridge/blob/2980e3ea/alt" undefined file-path="alt">Hii</FileRef>. Any URL without a scheme is converted to an absolute URL via home_url().

Sources: adapters/class-devto-adapter.php411-430

YAML Serialization

build_markdown() assembles the final document. It handles three value types:

PHP Type	YAML Output
`array`	`key: val1, val2, val3` (comma-joined inline)
`bool`	`key: true` or `key: false`
`string`	`key: value` — quoted with `"..."` if the value contains `:`, `\n`, or `\r`

The document is delimited with --- front matter fences.

Sources: adapters/class-devto-adapter.php442-466

Example output structure:

---
title: My Post Title
description: A short description of the post content.
tags: php, wordpress, open-source, web-dev
published: false
cover_image: https://example.com/wp-content/uploads/image.jpg
canonical_url: https://example.com/my-post/
series: Tutorials
---

Post body in Markdown...

Interface Methods That Return Empty Strings

DevTo_Adapter is API-based, so three Adapter_Interface methods are not applicable. They exist only to satisfy the interface contract and always return ''.

Method	Returns	Reason
`get_file_path(post)`	`''`	No file is written to disk
`get_images_dir(post_id)`	`''`	Images are referenced by URL, not stored locally
`get_featured_image_name(basename, ext)`	`''`	No local filename needed

The Media_Processor checks these return values before attempting file operations, so returning empty strings safely short-circuits any file-writing logic. See Media Processor for how this is handled upstream.

Sources: adapters/class-devto-adapter.php100-102 adapters/class-devto-adapter.php478-481 adapters/class-devto-adapter.php494-497

Comparison with File-Based Adapters

Concern	Hugo Adapter	Astro Adapter	DevTo Adapter
Output format	Markdown + TOML/YAML front matter	MDX + YAML front matter	Markdown + YAML front matter
Delivery mechanism	Git commit via GitHub API	Git commit via GitHub API	HTTP POST/PUT via Dev.to API
`get_file_path()`	Non-empty path	Non-empty path	`''`
`get_images_dir()`	Non-empty path	Non-empty path	`''`
Image handling	Copied to repo via Media_Processor	Copied to repo via Media_Processor	Absolute URL referenced inline
HTML conversion	`HTMLToMarkdown` library	`HTMLToMarkdown` library + Gutenberg cleanup	Custom regex pipeline
Front matter source	User-defined template with placeholders	Fixed YAML fields	Fixed YAML fields (Dev.to schema)

For details on the Hugo and Astro adapters, see Hugo Adapter and Astro Adapter.