Improve SEO: PyPI keywords, alternatives comparison, docs site

.github/workflows/docs.yml

@@ -0,0 +1,42 @@
+name: Deploy docs site
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "README.md"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch: {}
+
+permissions:
+  contents: write
+
+concurrency:
+  group: docs-deploy
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install MkDocs
+        run: pip install mkdocs-material
+
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Build (strict)
+        run: mkdocs build --strict
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force --clean

.gitignore

@@ -13,6 +13,9 @@ docxodus/**/obj/*
 packages/*/src/*/_binaries/*.tar.gz
 packages/*/src/*/_binaries/*.zip
 
+# MkDocs build output
+site/
+
 # C extensions
 *.so
 

README.md

@@ -1,14 +1,21 @@
-# Python-Redlines: Docx Redlines (Tracked Changes) for the Python Ecosystem
+# Python-Redlines: Open-Source DOCX Comparison for Python
 
-Generate tracked-change "redline" `.docx` documents from Python — compare two Word files
-and get back a third document showing every insertion, deletion, and (optionally) move as
-native Word tracked changes.
+Open-source DOCX comparison tool to generate native Word tracked changes (redlines) in
+Python — compare two Word files and get back a third document showing every insertion,
+deletion, and (optionally) move as native Word tracked changes, **without any MS Word
+dependency**.
 
 Comparing `.docx` documents has long been dominated by commercial software, with cost
 barriers and little integration flexibility. Python-Redlines brings open-source `.docx`
 redlining to the Python ecosystem so legal hackers, hobbyists, and product teams can build
 on it freely: two documents in, one redline out.
 
+**🔗 Try it now: [redlines.opensource.legal](https://redlines.opensource.legal)** — a
+live browser demo of the comparison engine, no install required. See also the
+[full documentation site](https://jsv4.github.io/Python-Redlines/) and
+[Python-Redlines vs. commercial alternatives](docs/alternatives.md) (Draftable API,
+Cloudmersive, server-side MS Word automation).
+
 ## Quick Start
 
 The **default engine is [Docxodus](https://github.com/JSv4/Docxodus)** — a modernized,
@@ -313,6 +320,38 @@ The engines produce slightly different stdout messages:
 The revision counts differ between the two Docxodus engines because the algorithms differ,
 not because either is wrong.
 
+## Python-Redlines vs. Commercial Alternatives
+
+Looking for a `.docx` comparison tool and weighing it against a paid API? Short
+version: Python-Redlines is a free, MIT-licensed, self-hosted library — your documents
+never leave your process, there's no per-comparison fee, and it works fully offline.
+The full write-up, including feature-by-feature tables, lives in
+[docs/alternatives.md](docs/alternatives.md):
+
+### Python-Redlines vs Draftable API
+
+[Draftable](https://draftable.com/)'s document comparison API is metered per
+comparison and requires sending your documents to a third-party cloud service.
+Python-Redlines runs in-process with no per-call cost, no network dependency, and full
+source availability (MIT license). See
+[the detailed comparison](docs/alternatives.md#python-redlines-vs-draftable-api).
+
+### Why choose Python-Redlines over Cloudmersive
+
+[Cloudmersive](https://cloudmersive.com/)'s document comparison endpoint is one part
+of a broader, metered, closed-source API. Python-Redlines has no API keys, no quotas,
+and keeps document bytes local to your own infrastructure. See
+[the detailed comparison](docs/alternatives.md#why-choose-python-redlines-over-cloudmersive).
+
+### The problem with server-side MS Word automation
+
+Driving a headless copy of MS Word via COM/Interop to generate tracked changes
+violates Microsoft's Terms of Service for unattended server-side use and is
+operationally fragile under concurrent load. Python-Redlines produces the same native
+Word tracked-changes `.docx` output via a lightweight, self-contained comparison
+engine — no Word installation, no TOS risk. See
+[the full breakdown](docs/alternatives.md#the-problem-with-server-side-ms-word-automation).
+
 ## Development
 
 ### Prerequisites

docs/alternatives.md

@@ -0,0 +1,123 @@
+# Python-Redlines vs. Commercial DOCX Comparison Alternatives
+
+Developers evaluating a way to compare Word documents and produce tracked-changes
+redlines programmatically usually land on one of a handful of commercial SDKs and
+cloud APIs. This page compares **Python-Redlines** — a free, open-source, self-hosted
+`.docx` comparison library for Python — against the most common alternatives, so you
+can pick the right tool for your architecture, budget, and compliance requirements.
+
+Try the engine yourself before reading further: **[live demo at
+redlines.opensource.legal](https://redlines.opensource.legal)** — upload two `.docx`
+files and download a real tracked-changes redline, no signup required.
+
+## The short version
+
+| | Python-Redlines | Draftable API | Cloudmersive | Server-side MS Word automation |
+|---|---|---|---|---|
+| **License cost** | Free, MIT | Paid, per-comparison or subscription | Paid, per-call metered | Requires a licensed, running MS Word/Office install |
+| **Where it runs** | In-process / self-hosted, any Python environment | Cloud API (your documents leave your infrastructure) | Cloud API (your documents leave your infrastructure) | Self-hosted, but against Microsoft's Terms of Service |
+| **Data privacy** | Documents never leave your process | Documents transit a third-party cloud service | Documents transit a third-party cloud service | Self-hosted, but fragile and unsupported |
+| **Output format** | Native Word tracked-changes `.docx` | Native Word tracked-changes `.docx` | Native Word tracked-changes `.docx` | Native Word tracked-changes `.docx` |
+| **Offline / air-gapped use** | ✅ Yes | ❌ No — requires network access to the vendor | ❌ No — requires network access to the vendor | ✅ Yes, if you can keep Word running headless |
+| **Rate limits / metering** | None — it's a local library call | Per-plan API quotas | Per-call billing | None, but see below |
+| **Move detection** | ✅ Yes (Docxodus engine) | ✅ Yes | Limited | Depends on Word version |
+| **Source availability** | ✅ Full source, MIT licensed | ❌ Closed source | ❌ Closed source | N/A |
+
+## Python-Redlines vs Draftable API
+
+[Draftable](https://draftable.com/) is a well-known commercial document comparison API
+that supports Word, PDF, and PowerPoint. It's a capable product, but it comes with
+trade-offs that matter for many Python teams:
+
+- **Cost scales with usage.** Draftable API pricing is metered by comparison volume.
+  For high-throughput legal-tech or document-automation pipelines — think a contract
+  lifecycle management platform diffing thousands of documents a day — that cost
+  compounds quickly. Python-Redlines has no per-comparison fee because it runs
+  in-process.
+- **Documents leave your infrastructure.** Every comparison is a network call to a
+  third-party service. For legal, healthcare, and financial-services workloads
+  handling privileged or regulated content, that's an extra data-processing agreement
+  to negotiate and an extra party in your threat model. Python-Redlines never sends
+  document content over the network — it's a local `.docx` diff and `.docx` output.
+- **No offline or air-gapped support.** Draftable requires live connectivity to its
+  API. Python-Redlines works in disconnected environments, CI pipelines, and
+  on-premise deployments because the comparison engine ships as a self-contained
+  binary embedded in the wheel.
+- **Closed source.** You cannot audit, fork, or patch Draftable's comparison logic.
+  Python-Redlines (and its underlying [Docxodus](https://github.com/JSv4/Docxodus)
+  and [Open-XML-PowerTools](https://github.com/OpenXmlDev/Open-Xml-PowerTools)
+  engines) is fully open source under the MIT license.
+
+**Where Draftable may still be the right call:** if you need a single hosted endpoint
+across many document formats (PDF, PPTX, images) with a support SLA and don't want to
+own any infrastructure, a managed API has real appeal. Python-Redlines is Word-`.docx`
+specific and you run it yourself.
+
+## Why choose Python-Redlines over Cloudmersive
+
+[Cloudmersive](https://cloudmersive.com/) offers a general-purpose document/file
+processing API, including a document comparison endpoint, billed per API call.
+
+- **Per-call cloud pricing vs. a free library call.** Cloudmersive's document
+  comparison is one endpoint in a broad, metered API surface. Python-Redlines has no
+  API keys, no quotas, and no bill — it's a `pip install` and a function call.
+- **Data privacy and residency.** Cloudmersive comparisons happen on Cloudmersive's
+  servers (or a licensed on-premise appliance, itself a paid tier). Python-Redlines
+  keeps document bytes in your own process the entire time — nothing to configure for
+  data residency because nothing leaves.
+- **Redline fidelity.** Python-Redlines' default engine (Docxodus) supports move
+  detection, format-change detection, and structure-aware diffing (via the optional
+  `docxdiff` algorithm) — producing native Word tracked-changes output tuned
+  specifically for `.docx`, rather than a generic document-diff endpoint shared across
+  many file formats.
+- **No vendor lock-in.** Cloudmersive's comparison logic is closed and proprietary.
+  Python-Redlines is MIT-licensed open source: inspect the C# comparison engines,
+  build them yourself, or contribute a fix upstream.
+
+## The problem with server-side MS Word automation
+
+Before dedicated comparison libraries existed, the common workaround was driving a
+real, licensed copy of Microsoft Word headlessly on a server — via COM automation,
+Office Interop, or similar — to generate tracked changes.
+
+- **It violates Microsoft's Terms of Service.** Microsoft explicitly does not support
+  or license unattended, server-side automation of desktop Office applications. This
+  is a real compliance and legal risk for any production system, not a theoretical
+  one.
+- **It's operationally fragile.** Desktop Word was never designed to run headless at
+  scale — it crashes under concurrent load, leaves zombie processes, requires a GUI
+  session or virtual display, and needs a full Windows + Office license per
+  worker/VM.
+- **It doesn't scale horizontally the way a library does.** Every comparison ties up
+  a full Office process; Python-Redlines' engines are lightweight, self-contained
+  .NET binaries invoked as subprocesses, safe to run concurrently and to containerize.
+
+Python-Redlines produces the same **native Word tracked-changes `.docx` output** —
+insertions, deletions, and moves that Word renders as real revisions — without ever
+launching Word, and without the TOS risk.
+
+## High-performance, cross-platform document diffing
+
+Python-Redlines' default engine, [Docxodus](https://github.com/JSv4/Docxodus), is a
+modernized, actively-maintained .NET 10 fork of Open-XML-PowerTools' `WmlComparer` —
+a high-performance document diffing engine purpose-built for cross-platform Word
+document comparison. It ships as a prebuilt, self-contained binary embedded directly
+in the Python wheel for Linux, macOS, and Windows (x64 and arm64), so there's no .NET
+SDK to install and no compilation step for end users — just `pip install
+python-redlines[docxodus]`.
+
+For enterprise developers evaluating open-source alternatives to commercial document
+diffing SDKs, that combination — open-source licensing, in-process execution, native
+Word tracked-changes output, and a high-performance comparison engine with move and
+format-change detection — is the core value proposition.
+
+## Try it yourself
+
+The fastest way to evaluate Python-Redlines against your own documents is the hosted
+demo: **[redlines.opensource.legal](https://redlines.opensource.legal)**. Upload an
+original and a modified `.docx`, and download a genuine Word tracked-changes redline
+generated by the same engine this library wraps.
+
+For local integration, see the [Quickstart guide](quickstart.md) or the
+[tutorial: how to compare two Word documents programmatically in
+Python](tutorials/how-to-compare-word-documents-python.md).

docs/index.md

@@ -0,0 +1,88 @@
+# Python-Redlines: Open-Source DOCX Comparison for Python
+
+**Python-Redlines** is an open-source DOCX comparison tool that generates native Word
+tracked changes (redlines) in Python — without any MS Word dependency. Compare two
+`.docx` files and get back a third document showing every insertion, deletion, and
+(optionally) moved block of text as real Word tracked changes, openable in Microsoft
+Word, LibreOffice, or Google Docs.
+
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "SoftwareApplication",
+  "name": "Python-Redlines",
+  "alternateName": "python-redlines",
+  "description": "Open-source DOCX comparison tool to generate native Word tracked changes (redlines) in Python without MS Word dependencies. Cross-platform Word document comparison with move and format-change detection.",
+  "url": "https://jsv4.github.io/Python-Redlines/",
+  "downloadUrl": "https://pypi.org/project/python-redlines/",
+  "codeRepository": "https://github.com/JSv4/Python-Redlines",
+  "applicationCategory": "DeveloperApplication",
+  "operatingSystem": "Linux, macOS, Windows",
+  "programmingLanguage": "Python",
+  "license": "https://opensource.org/licenses/MIT",
+  "offers": {
+    "@type": "Offer",
+    "price": "0",
+    "priceCurrency": "USD"
+  },
+  "author": {
+    "@type": "Person",
+    "name": "John Scrudato IV"
+  }
+}
+</script>
+
+**🔗 [Try the live demo](https://redlines.opensource.legal)** — upload two `.docx`
+files in your browser and download a real tracked-changes redline, no install
+required.
+
+## Why Python-Redlines
+
+- **Open source, MIT licensed** — inspect, fork, or contribute to the comparison
+  engines. No per-comparison fees, no API keys, no vendor lock-in.
+- **Runs in-process** — document bytes never leave your infrastructure, unlike
+  cloud comparison APIs. Works fully offline and in air-gapped environments.
+- **No Microsoft Word required** — no COM automation, no Office Interop, no Terms
+  of Service risk from server-side Word automation.
+- **Native tracked-changes output** — the redline `.docx` opens in Word with real
+  insertions, deletions, and moves, attributable to an author tag.
+- **Cross-platform, high-performance diffing engine** — the default
+  [Docxodus](https://github.com/JSv4/Docxodus) engine is a modernized .NET 10
+  fork of Open-XML-PowerTools' `WmlComparer`, shipped as a prebuilt, self-contained
+  binary embedded in the wheel for Linux, macOS, and Windows (x64/arm64) — nothing to
+  compile.
+
+## Install
+
+```bash
+pip install python-redlines[docxodus]
+```
+
+## Minimal example
+
+```python
+from python_redlines import DocxodusEngine
+
+with open("original.docx", "rb") as f:
+    original = f.read()
+with open("modified.docx", "rb") as f:
+    modified = f.read()
+
+engine = DocxodusEngine()
+redline_bytes, stdout, stderr = engine.run_redline("Reviewer", original, modified)
+
+with open("redline.docx", "wb") as f:
+    f.write(redline_bytes)
+```
+
+## Where to go next
+
+- [How to compare two Word documents programmatically in Python](tutorials/how-to-compare-word-documents-python.md) —
+  a hands-on, step-by-step tutorial
+- [Quickstart guide](quickstart.md)
+- [Python-Redlines vs. commercial alternatives](alternatives.md) — Draftable API,
+  Cloudmersive, and why not to automate MS Word server-side
+- [Developer guide](developer-guide.md) — repository layout, building the C# engines,
+  releasing
+- [GitHub repository](https://github.com/JSv4/Python-Redlines)
+- [PyPI package](https://pypi.org/project/python-redlines/)

docs/quickstart.md

@@ -59,7 +59,7 @@ with open('/path/to/redline_output.docx', 'wb') as f:
 ### Step 4: Tune the Comparison (optional, DocxodusEngine only)
 
 `DocxodusEngine` accepts keyword arguments to control move detection, granularity, and
-more. See the [main README](../README.md#comparison-settings-docxodusengine-only) for
+more. See the [main README](https://github.com/JSv4/Python-Redlines#comparison-settings-docxodusengine-only) for
 the full table.
 
 ```python
@@ -72,3 +72,10 @@ output = wrapper.run_redline(
 ```
 
 `XmlPowerToolsEngine` silently ignores these kwargs — switch engines if you need them.
+
+### See also
+
+- [How to compare two Word documents programmatically in Python](tutorials/how-to-compare-word-documents-python.md) —
+  a step-by-step tutorial covering this same flow in more depth
+- [Live demo](https://redlines.opensource.legal) — try a comparison in your browser
+- [Python-Redlines vs. commercial alternatives](alternatives.md)