Recursive AI

Write a line diff Markdown report in C#

OneDiff is a free, open-source diff library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

Show added and removed lines in a Markdown report, with unchanged lines for context.

Terminal
dotnet add package RecursiveAI.OneDiff

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
using OneDiff;
 
var diff = Diff.Lines(
    "red\nblue\n", "red\ngreen\n");
Console.Write(Diff.ToMarkdown(diff));
Text
```diff
@@ -1,2 +1,2 @@
 red
-blue
+green
```

Unzip the example, then dotnet run.

The full program

The full program also writes report.md. Use Diff.Lines to compare line by line, not a word-level diff.

C#
using OneDiff;
 
var diff = Diff.Lines(
    "red\nblue\n", "red\ngreen\n");
Console.Write(Diff.ToMarkdown(diff));
File.WriteAllText("report.md", Diff.ToMarkdown(diff));
Console.WriteLine("Wrote report.md");

dotnet run prints:

Text
```diff
@@ -1,2 +1,2 @@
 red
-blue
+green
```
Wrote report.md

Variations

Set file labels and remove context. This is a complete replacement program.

C#
using OneDiff;
using OneDiff.Output;
 
var diff = Diff.Lines(
    "red\nblue\n", "red\ngreen\n");
var renderer = new MarkdownRenderer
{
    ContextLines = 0,
    OldName = "before.txt",
    NewName = "after.txt"
};
Console.Write(renderer.RenderLines(diff));
Text
```diff
--- before.txt
+++ after.txt
@@ -2 +2 @@
-blue
+green
```

Compare text files. The zip includes these inputs, each ending with a newline:

before.txt:

Text
Status: draft
Owner: Ada

after.txt:

Text
Status: final
Owner: Ada

This complete replacement program reads both files and writes the Markdown report:

C#
using OneDiff;
 
var oldText = File.ReadAllText("before.txt");
var newText = File.ReadAllText("after.txt");
var diff = Diff.Lines(oldText, newText);
File.WriteAllText(
    "report.md", Diff.ToMarkdown(diff));
Console.WriteLine("Wrote report.md");
Text
Wrote report.md

The short answer

Create a line-token diff with Diff.Lines, then pass it to Diff.ToMarkdown. The result is a fenced diff block, not an HTML document or an inline word comparison. Write that string to a .md file when you want a report to attach to a review. The full program does both: it prints the block and saves report.md in the current directory.

How do you write a diff code block in Markdown?

A line report needs two things: the changed lines and enough unchanged text to locate them. OneDiff renders deleted lines with -, inserted lines with +, and context lines with a space. The @@ header gives the starting line and line count on each side. It uses one-based line numbers; a single-line range omits the count. These are the line-output rules used by the renderer, rather than labels added by the example program.

The default context is three lines on either side. If the unchanged gap between changes is at most twice the context setting, the changes share a hunk. That prevents repeated context from appearing twice. Choose zero context, as in the variation, for a compact list of changed lines; retain context when a reviewer needs to recognize the surrounding code or prose. OldName and NewName add file labels to the report. They do not read files: the strings passed to Diff.Lines remain the inputs.

An identical pair renders as the empty string. Treat that as “no changes,” not as a failed report. A displayed line without a final line terminator gets a no-newline note. Output lines end in \n, regardless of the input’s line endings; this report is a reading view, not a byte-preserving serialization of the original file.

How do you put a code block inside a Markdown code block?

Compared text can itself contain Markdown fences. The line renderer chooses three backticks or one more than the longest backtick run in the content. You don’t need to replace fences in the source text or surround the generated report with another fixed three-backtick block. Save the returned string directly, as the example does.

This matters when comparing documentation, where an added code sample may otherwise close the outer report early. The renderer owns the outer fence; the compared text remains inside it. Whether a viewer colors additions and deletions depends on that viewer’s support for the diff language label. The prefixes still carry the distinction in plain text.

Use line output for a file-change report. Use inline output when the desired result is prose with inserted and deleted words: Diff.ToMarkdownInline uses HTML del and ins tags and is a separate rendering choice. Neither report applies changes back to a file. For that workflow, create and apply a patch instead.

All onediff recipes