From d6b9e0b9c5dba8596f221b40ebdc7914eda38a8b Mon Sep 17 00:00:00 2001
From: Andras Schmelczer <andras@schmelczer.dev>
Date: Tue, 27 Oct 2026 18:43:09 +0000
Subject: [PATCH] Better callouts

---
 README.md                       |  2 +-
 docs/advanced-python.md         |  3 +++
 docs/advanced-ts.md             |  3 +++
 examples/website/src/index.html | 12 +++++++++---
 src/lib.rs                      |  4 +++-
 5 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index ac1901a..6aaef0b 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ A Rust, TypeScript, and Python library for merging conflicting text edits withou
 
 ✨ **[Try the interactive demo][8]** to see it in action!
 
-> Or read my [blog post](https://schmelczer.dev/articles/reconcile-text-3-way-merge/) on it!
+For the motivation and algorithm behind the library, read [Conflict-Free Three-Way Text Merging](https://schmelczer.dev/articles/reconcile-text-3-way-merge/).
 
 ### Install it in your project
 
diff --git a/docs/advanced-python.md b/docs/advanced-python.md
index ed2a8e9..18817fe 100644
--- a/docs/advanced-python.md
+++ b/docs/advanced-python.md
@@ -1,5 +1,8 @@
 # Advanced Usage (Python)
 
+For the motivation and algorithm behind the library, read
+[Conflict-Free Three-Way Text Merging](https://schmelczer.dev/articles/reconcile-text-3-way-merge/).
+
 ## Edit Provenance
 
 Track which changes came from where using `reconcile_with_history`:
diff --git a/docs/advanced-ts.md b/docs/advanced-ts.md
index dd1633d..c6d6957 100644
--- a/docs/advanced-ts.md
+++ b/docs/advanced-ts.md
@@ -1,5 +1,8 @@
 # Advanced Usage (TypeScript)
 
+For the motivation and algorithm behind the library, read
+[Conflict-Free Three-Way Text Merging](https://schmelczer.dev/articles/reconcile-text-3-way-merge/).
+
 ## Edit Provenance
 
 Track which changes came from where using `reconcileWithHistory`. The result's
diff --git a/examples/website/src/index.html b/examples/website/src/index.html
index e44926f..7d3748b 100644
--- a/examples/website/src/index.html
+++ b/examples/website/src/index.html
@@ -78,14 +78,20 @@
           </p>
 
           <p>
-            Ready to dive deeper? Check out the
+            Ready to dive deeper? Read
+            <a
+              href="https://schmelczer.dev/articles/reconcile-text-3-way-merge/"
+              target="_blank"
+              rel="noopener noreferrer"
+              >Conflict-Free Three-Way Text Merging</a
+            >
+            for the motivation and algorithm, browse the
             <a
               href="https://git.schmelczer.dev/andras/reconcile"
               target="_blank"
               rel="noopener noreferrer"
               >documentation</a
-            >
-            or try editing the text boxes below to see <code>reconcile-text</code> in
+            >, or try editing the text boxes below to see <code>reconcile-text</code> in
             action. Use the tokenisation options to experiment with different approaches -
             the Rust library also supports custom tokenisers.
           </p>
diff --git a/src/lib.rs b/src/lib.rs
index 7e86f90..1281d62 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -207,7 +207,9 @@
 //!
 //! ## Algorithm overview
 //!
-//! For detailed algorithm explanation, see the
+//! For the motivation and algorithm behind the library, read
+//! [Conflict-Free Three-Way Text Merging](https://schmelczer.dev/articles/reconcile-text-3-way-merge/).
+//! For a shorter overview, see the
 //! [README](https://git.schmelczer.dev/andras/reconcile/blob/main/README.md#how-it-works).
 
 mod operation_transformation;