Building ownwords: A Synthesis Coding Case Study

Owning my words meant being able to edit, move and publish them with tools I understood.

I built ownwords because I wanted to work on my WordPress articles as local Markdown, keep edits in Git and publish to more than one target. Terminology updates and link fixes made batch editing useful. Content preservation mattered just as much: a convenient editing workflow would be little help if conversion quietly dropped a paragraph.

I depended on it for my own publishing. I wanted to:

  1. Fetch existing WordPress articles as clean Markdown.
  2. Edit locally with the tools I chose.
  3. Make coordinated changes across the archive.
  4. Publish to WordPress and static sites.
  5. Verify that conversion preserved what I wrote.

I chose the architecture to serve those requirements, and AI helped implement it within those constraints.

Doing these jobs by hand across a large WordPress archive can take days, weeks or months, with plenty of opportunities for error. An author’s bio might appear in hundreds of posts. A rebrand or a change in disclosure requirements could call for coordinated edits. A domain move could require changes to canonical URLs and internal links, followed by checks for broken destinations. I also wanted cross-references between related articles, consistent style and formatting, and summaries, metadata or structured data across an archive. Keeping Markdown in Git let me use editorial tools for those jobs while treating WordPress as one publishing target among several.

ownwords is a Node.js toolkit for fetching, conversion, verification, export and publishing.

September 2026 update: The source comparisons below describe the September version of ownwords. The runnable conversion and permission examples were added with this update.

Preview an archive-wide edit

A product name can occur in prose, a quotation, a URL and a code sample. Finding all its occurrences is only the beginning of deciding which ones to change. That is why I wanted a preview step before an assistant applied edits across the archive.

The find-and-replace implementation supports dryRun: true. It builds a list of affected files with their slugs, paths, match counts and up to five matched strings per file. Both write paths are guarded by the dry-run condition. It can also include or exclude the front matter from the search.

That preview identifies where review is needed. It is not a full diff or a saved plan that binds a later invocation to unchanged inputs. I would inspect the actual proposed edits, preserve the original files and check the resulting diff before publishing. If the files change between preview and application, the earlier preview no longer describes the same input.

Fetch according to the available source

The documented fetching modes serve different access conditions. HTML fetching starts from an accessible page and depends on its structure. The configured REST API mode supplies article data and metadata such as categories, tags, author information and featured-image details. A public URL alone does not establish that every theme will convert correctly or that an API is accessible.

I saved complete JSON responses to support future bidirectional synchronization. At the time of this case study, ownwords did not yet perform that complete sync. Fetching, local editing and publishing were useful on their own, and the sidecars gave later synchronization work the original metadata to build on.

For HTML extraction, I specified the structures to try: an entry-content container, then an article element, then main. I specified what to remove, including sharing widgets, related posts, navigation, footers and comments, and what to retain: code, images and formatting. I refined the implementation by testing it against WordPress sites, identifying edge cases and directing fixes. The exercise below uses an explicit container rule so its expected document is clear.

Check where the article ends

A converter and its checker can lose the same text and still agree. This fragment from the teaching fixture contains a layout box inside the article, followed by more article content:

<div class="post entry-content">
<h1>A small post</h1>
<p>Lead <a href="https://example.test/reference">reference</a>.</p>
<div class="callout"><p>Inside the nested box.</p></div>
<p>Tail after the nested box.</p>
<pre><code class="language-js">const amount = 3;</code></pre>
</div>

The first closing div belongs to the callout. Stopping there loses the tail paragraph and the code block.

When two checks share the same mistake

The earlier converter excerpt used a non-greedy match that ended at the first closing div:

/<div[^>]*class="[^"]*entry-content[^"]*"[^>]*>([\s\S]*?)<\/div>/i

The verifier used the same expression to extract its comparison text. Both paths could therefore discard the same content. Agreement between their outputs did not establish that either had captured the article.

The complete example retains those extraction paths as labeled negative controls. One declares the missing variable from the published converter so the extraction behavior can be examined separately. A second retains the undeclared assignment and confirms that it raises a ReferenceError in strict mode.

These are defects in the excerpts previously published here. The ownwords source inspected on September 26, 2026 differs: its converter initializes its content variable, and its verifier reads the HTML and Markdown files. The teaching package does not establish that the application has the same failures.

Give the expected document its own source

The revised example uses parse5 to parse the HTML structure. It selects exactly one element whose class list contains the token entry-content, then gives that element's contents to Turndown for conversion. No matching container, or more than one, is an error.

That selection rule is a declared boundary for this example. A theme using another container needs its own selection rule and fixtures. Falling back to the entire page would silently change which content the test was meant to protect.

I imposed a small dependency set as an architectural constraint. In the December 6, 2025 manifest, ownwords had two production dependencies: Turndown and its GFM plugin. I used Node.js built-ins for the other work, including HTTP, file operations and argument handling. I wanted fewer packages to audit and upgrade, and explicit control over the behavior our own code supplied. Choosing those boundaries was part of the craft. A small dependency set still needs testing and can still encounter version conflicts.

The September 2026 manifest has three production dependencies, adding gray-matter. The teaching exercise makes a further, specific case for a parser library: parse5 handles nested HTML structure that the short regex gets wrong.

The expected Markdown was written from the visible HTML fixture. It is stored as a literal file:

# A small post

Lead [reference](https://example.test/reference).

Inside the nested box.

Tail after the nested box.

```js
const amount = 3;
```

The verifier reads the generated file and this expected file, then compares their bytes. It does not extract a second expectation from the HTML through the converter's selection logic. The fixture specifies one final newline.

Exact comparison is useful here because the intended formatting is small enough to inspect. For a larger migration, decide which differences are acceptable before adding normalization. A rule that ignores whitespace everywhere, for example, could also erase a difference inside a code block.

The expectation itself needs review. Regenerating it automatically whenever the converter changes would make the converter the authority over what it was supposed to preserve.

Run the conversion and its failures

After extracting the package, use Node.js 24 or later. The permission tests require a POSIX system; the recorded runs below used macOS.

npm ci --ignore-scripts --no-audit --no-fund
npm test
mkdir -p .work
node convert-file.mjs fixtures/nested.html .work/article.md
node verify-file.mjs .work/article.md fixtures/expected.md

The final command prints:

PASS: Markdown matches the literal expected file

The package also contains a version with the URL changed from the intended reference to a different destination:

node verify-file.mjs fixtures/wrong-link.md fixtures/expected.md

That command exits 1. Its word count is unchanged. The test suite separately changes a word without changing the count; that fails too.

CaseRequired observation
Nested article contentThe tail paragraph, exact link and code survive conversion.
Old extraction pathsThey agree while both omit the tail.
Missing or ambiguous containerConversion rejects the input.
Changed word or URLThe literal-file check rejects the output.
Incomplete published assignmentStrict-mode execution raises a ReferenceError.
File commandsThe producer reads the HTML file, writes Markdown and passes it to the independent comparison.

All 18 test groups passed locally on macOS with Node.js 24.19.0 and 26.8.2. The Node 24 run used a clean copy with dependencies installed from the lock file. The remaining groups check the configuration example below.

These results cover the supplied synthetic documents and file operations.

Preserve literal code on export

The return from Markdown to HTML has its own preservation rule. If a code block contains **bold**, the published code should still show the asterisks. Applying Markdown emphasis rules inside that block would change the example the author wrote.

The export function protects fenced code with temporary placeholders, applies formatting to the surrounding text, then restores escaped code. It protects inline code separately. The order matters because the same characters have different meanings inside and outside code.

This is a design mechanism to test, not a guarantee that the renderer covers every Markdown form. The function also trims fenced-code content before wrapping it in HTML. A whitespace-sensitive example therefore needs an explicit expected result. I would include literal emphasis markers, angle brackets and meaningful indentation among the export fixtures, and review their rendered output.

Creation modes do not repair existing permissions

Publishing also meant handling credentials. I required an owner-only configuration file, a private configuration directory, environment overrides for automation and a permission check. The December configuration module used ~/.ownwords/; the September version uses the XDG configuration location. Both support a complete site/username/password environment configuration or a password override.

For WordPress access I chose Application Passwords. WordPress’s authentication documentation describes using them with REST requests over HTTPS. The local file holding them still needs protection.

The earlier configuration example supplied mode 0700 when creating a directory and 0600 when writing a file. Node's filesystem documentation distinguishes creation permissions from changes to an existing object. Passing a mode to writeFile does not tighten an existing file's permissions.

The package demonstrates the difference using dummy configuration:

node permission-demo.mjs

Its observed modes were:

StageDirectoryFile
Existing objects07550644
Creation options supplied again07550644
Explicit mode changes07000600

The example writer requires an owned, private parent. It opens the configuration directory and file with no-follow flags, checks the opened objects, and applies the requested modes explicitly. It changes the file's mode before truncating and writing its new content.

The tests also reject a file symlink, a directory symlink, a hard link and a directory placed where the file should be. Dummy targets outside the selected configuration path remain unchanged. If JSON serialization fails, the previous file content remains intact.

This demonstrates POSIX mode bits under the stated local conditions. The writer assumes trusted ancestors and no hostile process racing to replace paths. It does not manage ACLs, encrypt secrets or make the write atomic; the permission example rejects Windows. Those properties would need their own design and verification before using such a writer for real credentials.

Keep the source beside the expected result

For a migration, I would keep a fixture for each materially different source structure and review its expected document before running the conversion across an archive. A gallery, an embedded video and a code-heavy article may need different preservation rules. Record the original source alongside the expected result so a later change can be judged against both.

When a coding assistant helps implement the pipeline, give it the source document, the intended output and the rejected cases. Then run the file commands and inspect a failed case.

A publishing tool I could maintain

By the December 2025 case study, I had been using ownwords for several months: 53 articles managed as local Markdown, version-controlled content with Git history, batch terminology updates, and publishing paths to rajiv.com on WordPress and synthesiscoding.org as a static site. Verification was catching conversion issues before they reached production.

The investment in architecture and verification had paid back many times over. It gave me confidence when updating terminology across the archive or publishing to WordPress. When something went wrong, I could debug it because I understood the system.

An undirected coding assistant would not have arrived at this architecture. The preview API, independent conversion checks, constrained dependencies, two fetching modes, credential rules and future-sync sidecars came from thinking about how people would use and maintain the tool. I had to supply that direction.

That is what synthesis coding produces: systems we can maintain, extend and trust. I set the architecture, directed implementation within its constraints, required independent checks and maintained my understanding throughout.

Read the open source code alongside the tests and compare it with what your archive needs. The broader case for retaining code is in Why Synthesis Coding Still Writes Code in the Age of LLMs. The Synthesis Engineering Framework takes the method into an organization; Synthesis Coding with Claude Code describes the technical workflow.