# Migrate a Go Project From Blackfriday to goldmark

Yes. An agent swaps the Markdown renderer, turns on the goldmark options that match what Blackfriday did by default, and diffs the HTML of your real pages.

[Run this on Rush](https://cloud.getrush.ai/run/migrate-blackfriday-to-goldmark/blackfriday/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

Swapping one Markdown library for another is a one-line change that alters the HTML of every page, so the agent treats it as an output migration and measures the output. It first finds each call and what options it passes. In a static site generator like zserge/zs there is one: `buildMarkdown` in `zs.go` sets `v["content"] = string(blackfriday.Run([]byte(content)))`, with no options, and `go.mod` requires `gopkg.in/russross/blackfriday.v2 v2.0.0+incompatible`. That import path is a reason to move on its own account. Blackfriday's later v2 releases declare their module as `github.com/russross/blackfriday/v2`, so asking Go for a newer version through the gopkg.in path fails with `module declares its path as: github.com/russross/blackfriday/v2 but was required as: gopkg.in/russross/blackfriday.v2`.

`blackfriday.Run` with no arguments is not a bare renderer. It turns on tables, fenced code, autolinks, strikethrough and definition lists, converts straight quotes, `--` and `...` to typographic entities, writes void tags as `<hr />`, and passes raw HTML through. `goldmark.New()` with no arguments does none of that: it is strict CommonMark, a table stays a paragraph of pipes, and raw HTML is replaced by the comment `<!-- raw HTML omitted -->`. For this project the last point decides whether the tool still works, because the README tells users to keep texts in Markdown or HTML and to call plugins from placeholders whose output lands in the page. The agent therefore builds one package-level converter with `extension.GFM`, `extension.Typographer` and `extension.DefinitionList`, plus `html.WithUnsafe()` and `html.WithXHTML()`, and calls its `Convert` into a `bytes.Buffer`, returning the error that `Run` never had.

Then it renders the same inputs through both libraries and prints the two results side by side: a heading and paragraph, a table, a fenced block, strikethrough with a bare URL, a definition list, quoted text with dashes and a fraction, and block and inline HTML. With the options above most rows match apart from whitespace. Two differences remain and it reports them as such: Blackfriday puts an empty line between block elements and goldmark does not, and Blackfriday's `1/2` fraction markup has no goldmark equivalent.

That empty line matters here. `zs_build_test.go` builds each directory under `testdata` and compares an MD5 of every generated file with the copy stored in `.test`. After the swap `TestBuild` fails on `about.html`, `posts/hello.html` and `posts/update.html`, the three pages that come from Markdown. The agent diffs each against its stored copy, shows the only change is the missing blank line after the `<h1>`, and regenerates the three golden files in the same commit with that diff in the description. It also runs the full suite before the change: `TestRun` already fails on a current Go toolchain with `exec: "echo": cannot run executable found relative to current directory`, which has nothing to do with Markdown and is reported, not fixed.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Replace Blackfriday (github.com/russross/blackfriday, its /v2 path or the gopkg.in/russross/blackfriday.v2 path) with github.com/yuin/goldmark in this Go project. First run the test suite and save the output, noting any test that fails before you change anything. Find every call into Blackfriday and write down the extensions and HTML flags it uses; a call with no options uses the library's defaults, so look those up in the version pinned in go.mod and list them. Read the README and any templates to learn whether users are expected to put raw HTML or generated HTML inside Markdown. Build one goldmark converter, created once and reused, with the extensions and renderer options that reproduce the old behaviour: GFM for tables, strikethrough and autolinks, Typographer if smart punctuation was on, DefinitionList and Footnote if they were on, WithUnsafe only if raw HTML passed through before, WithXHTML if void tags were self-closed, and heading ids only if they were generated before. Handle the error Convert returns. Before trusting it, write a small throwaway program that renders the same inputs through both libraries and prints both results: headings, a table, a fenced code block, strikethrough, a bare URL, a definition list, quotes with dashes and an ellipsis, a hard line break, and block and inline raw HTML. Add every Markdown file in the repository's testdata, examples or docs to that comparison. Report each difference that remains and whether it is whitespace only. If tests compare generated HTML with stored files, regenerate those files only after showing the diff for each, and say which changed for whitespace alone. Run go mod tidy, confirm Blackfriday and sanitized_anchor_name are gone from go.mod, and list any other line that changed, including the go directive. Do not commit the comparison program. Open a pull request with the comparison table and the test output before and after.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

A pull request that changes the import block and `buildMarkdown` in `zs.go`, adds the converter with its five options, replaces three files under `testdata/blog/.test`, and updates `go.mod` and `go.sum`. Blackfriday and its indirect helper `github.com/shurcooL/sanitized_anchor_name` leave the module file; `github.com/yuin/goldmark` arrives, and the `go` directive, 1.13 in this repository, is raised by the new dependency.

The description leads with the comparison table: one row per input, the HTML from each library, and a verdict of identical, whitespace only, or different. A reviewer reads the rows marked different and decides whether each is acceptable for a site that is already published. They read the choice of `html.WithUnsafe()` with the same care. It keeps existing pages rendering as before, and it means Markdown from an untrusted author can inject script, exactly as it could under Blackfriday; a project that renders user input should sanitise the result or leave the option off and accept the changed output.

The golden files are shown as diffs, not just replaced, so the reviewer can see each one loses a single empty line. The failing `TestRun` appears in both test outputs with the same message, which is the evidence that this pull request did not cause it.

## Run it on every repository that imports Blackfriday

Blog engines, documentation tools and README renderers inside one organisation often share this dependency. Start one run per repository from a script: for each repository whose `go.mod` names `russross/blackfriday`, send this body to `POST /o/{org}/sessions` with that repository in `resources`. Give each call a `request_id` that is a UUID v5 of the repository name so the script can be rerun safely.

Each request answers `202` with the session. Poll `GET /o/{org}/sessions/{id}` until it completes, or set a `webhook_url` on the key and act on `run.completed`. Review these pull requests one at a time: each has its own comparison table, and the differences depend on what Markdown that project actually contains.

## Why run it on Rush?

The risk in this job is silent: the code compiles, the pages build, and some of them now show pipes where a table was or drop an embedded video. Only rendering real content through both libraries shows it. The agent's sandbox has the old and the new module installed at once, builds the comparison program, runs it over the repository's own Markdown, and the output is kept in the session's transcript where the reviewer can read the HTML for themselves.

It also separates what changed from what was already broken. The suite runs before the first edit on the same toolchain that runs it after, so a test that fails for an unrelated reason is named up front and does not get blamed on the migration, or quietly patched inside it.

## Frequently asked questions

### Why does goldmark print "raw HTML omitted" where my HTML used to be?

goldmark's renderer drops raw HTML and dangerous links unless it is created with `html.WithUnsafe()`. Blackfriday passed HTML through by default. Turn the option on if your authors are trusted and their pages rely on embedded HTML, and sanitise the output if they are not.

### Will my tables and strikethrough still render?

Only with `extension.GFM` enabled, which adds tables, strikethrough, autolinks and task lists. Blackfriday's default call enabled the first three without being asked, so a project that never configured anything still depends on them. The agent's comparison includes a table and a strikethrough row to prove the option took effect.

### Will the generated HTML be byte-identical?

No. Even with matching options, goldmark separates block elements with a single newline where Blackfriday writes an empty line, so any test that hashes output will fail once. The pull request shows those diffs and regenerates the stored files.

### Do heading anchors change?

They can. `blackfriday.Run` without options emits headings with no `id`, and goldmark does the same unless `parser.WithAutoHeadingID()` is set. A project that enabled Blackfriday's heading ids explicitly gets that option, and the agent compares the generated ids, because the two libraries do not always build the same slug from the same title.

## More jobs like this: Upgrade dependencies weekly

- [Migrate From Bluebird to Native Promises in a Node.js Library](https://getrush.ai/run/migrate-bluebird-to-native-promises/bluebird/)
- [Replace body-parser With express.json() in an Express App](https://getrush.ai/run/migrate-body-parser-to-express-json/body-parser/)
- [Migrate From the Archived github.com/boltdb/bolt to go.etcd.io/bbolt in a Go Service](https://getrush.ai/run/migrate-boltdb-to-bbolt/boltdb/)
- [Migrate From boto to boto3 in a Python Service](https://getrush.ai/run/migrate-boto-to-boto3/boto/)
- [Convert a CoffeeScript Project to Modern JavaScript With decaffeinate](https://getrush.ai/run/migrate-coffeescript-to-javascript/coffeescript/)
- [Migrate a Go Project From dep (Gopkg.toml) to Go Modules](https://getrush.ai/run/migrate-dep-to-go-modules/dep/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
