All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.

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

Keep reading