From 8343edcdf13772c3ac3d493698e0adeb93eef815 Mon Sep 17 00:00:00 2001
From: Dolan Miu <dolan_miu@hotmail.com>
Date: Sun, 19 Mar 2023 03:26:02 +0000
Subject: [PATCH] Update documentation

---
 README.md             |  2 +-
 docs/_coverpage.md    |  6 +--
 docs/_sidebar.md      |  8 +++-
 docs/usage/patcher.md | 94 +++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 105 insertions(+), 5 deletions(-)
 create mode 100644 docs/usage/patcher.md

diff --git a/README.md b/README.md
index c5ce2ad461..4dcc91b325 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-    Easily generate .docx files with JS/TS. Works for Node and on the Browser.
+    Easily generate and modify .docx files with JS/TS. Works for Node and on the Browser.
 </p>
 
 ---
diff --git a/docs/_coverpage.md b/docs/_coverpage.md
index ae27b1a3fb..b8a546f3a4 100644
--- a/docs/_coverpage.md
+++ b/docs/_coverpage.md
@@ -1,10 +1,10 @@
 <img src="https://i.imgur.com/37uBGhO.gif" alt="drawing" style="width:200px;"/>
 
-> Easily generate .docx files with JS/TS. Works for Node and on the Browser. :100:
+> Easily generate and modify .docx files with JS/TS. Works for Node and on the Browser. :100:
 
 -   Simple, declarative API
--   60+ usage examples
--   Battle tested, mature, 99%+ coverage
+-   80+ usage examples
+-   Battle tested, mature, 99.9%+ coverage
 
 [GitHub](https://github.com/dolanmiu/docx)
 [Get Started](#Welcome)
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
index 8805f6a417..048b62397c 100644
--- a/docs/_sidebar.md
+++ b/docs/_sidebar.md
@@ -1,6 +1,8 @@
 -   [Getting Started](/)
 
--   [Examples](https://github.com/dolanmiu/docx/tree/master/demo)
+-   Examples
+
+    -   [Demos](https://github.com/dolanmiu/docx/tree/master/demo)
 
 -   API
 
@@ -36,6 +38,10 @@
 
     -   [Packers](usage/packers.md)
 
+-   Modifying Existing Documents
+
+    -   [Patcher](usage/patcher.md)
+
 -   Utility
 
     -   [Convenience functions](usage/convenience-functions.md)
diff --git a/docs/usage/patcher.md b/docs/usage/patcher.md
new file mode 100644
index 0000000000..6f76b1d180
--- /dev/null
+++ b/docs/usage/patcher.md
@@ -0,0 +1,94 @@
+# Patcher
+
+The patcher allows you to modify existing documents, and add new content to them.
+
+!> The Patcher requires an understanding of [Paragraphs](usage/paragraph.md).
+
+---
+
+## Usage
+
+```ts
+import * as fs from "fs";
+import { patchDocument } from "docx";
+
+patchDocument(fs.readFileSync("My Document.docx"), {
+    patches: {
+        // Patches here
+    },
+});
+```
+
+## Patches
+
+The patcher takes in a `patches` object, which is a map of `string` to `Patch`:
+
+```ts
+interface Patch {
+    type: PatchType;
+    children: FileChild[] | ParagraphChild[];
+}
+```
+
+| Property | Type                              | Notes    | Possible Values                                                                                                                      |
+| -------- | --------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| type     | `PatchType`                       | Required | `DOCUMENT`, `PARAGRAPH`                                                                                                              |
+| children | `FileChild[] or ParagraphChild[]` | Required | The contents to replace with. A `FileChild` is a `Paragraph` or `Table`, whereas a `ParagraphChild` is typical `Paragraph` children. |
+
+### How to patch existing document
+
+1. Open your existing word document in your favorite Word Processor
+2. Write tags in the document where you want to patch in a mustache style notation. For example, `{{my_patch}}` and `{{my_second_patch}}`.
+3. Run the patcher with the patches as a key value pair.
+
+## Example
+
+### Word Document
+
+![Word Document screenshot](https://i.imgur.com/ybkvw6Z.png)
+
+### Patcher
+
+?> Notice how there is no handlebar notation in the key.
+
+The patch can be as simple as a string, or as complex as a table. Images, hyperlinks, and other complex elements within the `docx` library are also supported.
+
+```ts
+patchDocument(fs.readFileSync("My Document.docx"), {
+    patches: {
+        my_patch: {
+            type: PatchType.PARAGRAPH,
+            children: [new TextRun("Sir. "), new TextRun("John Doe"), new TextRun("(The Conqueror)")],
+        },
+        my_second_patch: {
+            type: PatchType.DOCUMENT,
+            children: [
+                new Paragraph("Lorem ipsum paragraph"),
+                new Paragraph("Another paragraph"),
+                new Paragraph({
+                    children: [
+                        new TextRun("This is a "),
+                        new ExternalHyperlink({
+                            children: [
+                                new TextRun({
+                                    text: "Google Link",
+                                }),
+                            ],
+                            link: "https://www.google.co.uk",
+                        }),
+                        new ImageRun({ data: fs.readFileSync("./demo/images/dog.png"), transformation: { width: 100, height: 100 } }),
+                    ],
+                }),
+            ],
+        },
+    },
+});
+```
+
+---
+
+## Demo
+
+_Source: https://github.com/dolanmiu/docx/blob/master/demo/85-template-document.ts_
+
+[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/85-template-document.ts ":include :type=code typescript")