Docs: Add documentation

email/libmailmerge/src/previews/sidecarData.ts

@@ -112,7 +112,7 @@ export async function writeMetadata(
     }
     const metadataFile = getRecordPreviewPrefixForMetadata(record, fileNamer);
     logger.debug(`Writing metadata for ${fileNamer(record)} to ${metadataFile}`);
-    await writeSidecarFile(previewsRoot, metadataFile, sidecarData);
+    await writeSidecarFile(join(previewsRoot, metadataFile), sidecarData);
     return Promise.resolve();
 }
 
@@ -165,12 +165,8 @@ export function getSidecarMetadata(
 /**
  * Write the sidecar metadata file for a record
  */
-export async function writeSidecarFile(
-    previewsRoot: string,
-    metadataFile: string,
-    sidecar: SidecarData,
-) {
-    await fs.writeFile(join(previewsRoot, metadataFile), JSON.stringify(sidecar, null, 4));
+export async function writeSidecarFile(metadataFilePath: string, sidecar: SidecarData) {
+    await fs.writeFile(metadataFilePath, JSON.stringify(sidecar, null, 4));
 }
 
 /**

email/mailmerge-cli/README.md

@@ -1,5 +1,38 @@
 # mailmerge-cli
 
+## Quick start
+
+1. Run `npm install` from the root of the repo
+2. Run `npm run build` in this folder (`email/mailmerge-cli`)
+3. Run `npm link` in this folder - this adds `docsoc-mailmerge` to your path
+4. In a blank directory somewhere (known as the "mailmerge workspace"), create these folders & files:
+    1. `./data/names.csv` - CSV file with at the minimum `email` & `subject` columns
+    2. `./templates/template.md.njk` - nunjucks markdown template for your emails (see `/email/workspace/templates/tempkate.md.njk` for an example, where `/` is the repo root)
+    3. `./templates/wrapped.html.njk`, a HTML wrapper for the email (use the contents of `/email/workspace/wrapper.html.njk`)
+5. Run `docsoc-mailmerge generate nunjucks --help` and read the help text
+6. Run `docsoc-mailmerge generate nunjucks ./data/names.csv -o ./output --htmlTemplate=./templates/wrapper.html.njk`. You'll be asked for a runname: generated emails will be placed at `./output/<runname>`
+    1. Each record in the CSV will result in 3 files in `./output/<runname>`: an editable markdown file to allow you to modify the email, a HTML rendering of the markdown that you should not edit, and a `.json` metadata file
+    2. The HTML files, which is what is actually sent, can be regenerated after edting the markdown files with `regenerate` command (see below)
+    3. If you want to edit the to address or subject after this point you will need to edit the JSON files; csv edits are ignored. If you edit the CSV, delete all outputs and run generate again.
+7. Edit the generated markdown files - this allows you to edit the emails
+8. Run `docsoc-mailmerge regenerate ./output/<runname>` - this will re-render the markdown files into the HTML previews. These HTML previews are then what is sent to receipients. You can call `regenerate` as many times as you want.
+9. Once you've edited & checked all the email markdowns as needed & checked and regenerated if needed the HTMLs, run this command to send the emails: `docsoc-mailmerge send ./output/<runname>`.
+    1. NOTE: Send does not run `regenerate`, so if you edited any markdown files ensure you ran `regenerate` before running `send`
+10. Done! Sent email previews will be moved to `./output/<runname>/sent` to prevent double sending if the send is stopped halfway through.
+
+### Attachments
+
+I recommend placing attachments in an `attachments` folder.
+
+2 ways to add attachments:
+
+1. If you want a different attachments per email, create a column called `attachment` in the CSV with the path to the attachment relative to the workspace root - e.g. if you CSV is in `./data/names.csv` and the attachment in `./attachment/image.jpg`, the CSV row should have `./attachments/image.jpg` as it's value in the `attachment` column
+    1. Use multiple columns e.g. `attachment1`, `attachment2` for multiple attachments
+    2. When you run `generate` you will be asked which columns to use for attachments
+    3. To edit which attachment to use ater `generate`, edit the JSON metadata files.
+2. If you want the same attachment to all emails, use the `-a` flag of generate, e.g. `docsoc-mailmerge generate nunjucks ./data/names.csv -o ./output -a ./attachments/image.jpg -a ./attachments/image2.jpg`.
+    1. Note that if you pass the CLI option, any info about attachments in the CSV is ignored.
+
 This library was generated with [Nx](https://nx.dev).
 
 ## Building

email/mailmerge-cli/src/common/generate.ts

@@ -190,5 +190,5 @@ export default async function generatePreviews(opts: CliOptions) {
         }),
     );
 
-    logger.info("Done! Review previews and then send.");
+    logger.info(`Done! Review previews at ${previewsRoot} and then send.`);
 }

email/mailmerge-cli/src/common/rerender.ts

@@ -55,7 +55,7 @@ export async function rerenderPreviews(directory: string) {
         );
 
         logger.info(`Updating sidecar metadata for ${name} at ${sidecar.$originalFilepath}...`);
-        await writeSidecarFile(directory, sidecar.$originalFilepath, sidecar);
+        await writeSidecarFile(sidecar.$originalFilepath, sidecar);
 
         logger.info(`Finished rerendering ${name}`);
     }

email/workspace/output/slight.rose.opossum/sent/Kishan-metadata.json

@@ -0,0 +1,43 @@
+{
+    "name": "Kishan",
+    "record": {
+        "name": "Kishan",
+        "email": "[email protected]",
+        "subject": "DoCSoc x Kishan",
+        "attachment1": "./attachments/DoCSoc Sponsorship Proposal 24-25.pdf",
+        "attachment2": "./attachments/munch.jpg"
+    },
+    "engine": "nunjucks",
+    "engineOptions": {
+        "templatePath": "templates/template.md.njk",
+        "rootHtmlTemplate": "templates/wrapper.html.njk"
+    },
+    "files": [
+        {
+            "filename": "Kishan__nunjucks__Preview-Markdown.md",
+            "engineData": {
+                "name": "Preview-Markdown.md",
+                "metadata": {
+                    "type": "markdown"
+                }
+            }
+        },
+        {
+            "filename": "Kishan__nunjucks__Preview-HTML.html",
+            "engineData": {
+                "name": "Preview-HTML.html",
+                "metadata": {
+                    "type": "html"
+                }
+            }
+        }
+    ],
+    "email": {
+        "to": "[email protected]",
+        "subject": "DoCSoc x Kishan"
+    },
+    "attachments": [
+        "./attachments/munch.jpg"
+    ],
+    "$originalFilepath": "output/slight.rose.opossum/Kishan-metadata.json"
+}

email/workspace/output/slight.rose.opossum/sent/Kishan__nunjucks__Preview-HTML.html

@@ -0,0 +1,26 @@
+<!-- DoCSoc Mail Merge Wrapper - used to wrap results rendered from Markdown -->
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8">
+		<meta name="viewport" content="width=device-width, initial-scale=1.0">
+	</head>
+	<body>
+		<p>Dear Kishan,</p>
+<p>I hope you are well. Do you like the photo I sent?</p>
+<p>If you are seeing this email, it means that the new mail merge tool is working as expected.</p>
+<p>For it was this email you see, that was sent by complete mail merge pipeline.</p>
+<p>Of course, some things are still missing, namely:</p>
+<ul>
+<li>Attachments</li>
+<li>Crash-proofing so you don't double send emails</li>
+<li>A nice CLI</li>
+<li>Docs</li>
+</ul>
+<p>But it does work!</p>
+<p>Kind regards,<br>
+Some TypeScript code on behalf of Kishan Sambhi (he/him)<br>
+DoCSoc Vice President</p>
+
+	</body>
+</html>

email/workspace/output/slight.rose.opossum/sent/Kishan__nunjucks__Preview-Markdown.md

@@ -0,0 +1,20 @@
+Dear Kishan,
+
+I hope you are well. Do you like the photo I sent?
+
+If you are seeing this email, it means that the new mail merge tool is working as expected.
+
+For it was this email you see, that was sent by complete mail merge pipeline.
+
+Of course, some things are still missing, namely:
+
+-   Attachments
+-   Crash-proofing so you don't double send emails
+-   A nice CLI
+-   Docs
+
+But it does work!
+
+Kind regards,
+Some TypeScript code on behalf of Kishan Sambhi (he/him)
+DoCSoc Vice President

email/workspace/output/specified.brown.grasshopper/Kishan-metadata.json

@@ -0,0 +1,42 @@
+{
+    "name": "Kishan",
+    "record": {
+        "name": "Kishan",
+        "email": "[email protected]",
+        "subject": "DoCSoc x Kishan",
+        "attachment1": "./attachments/DoCSoc Sponsorship Proposal 24-25.pdf",
+        "attachment2": "./attachments/munch.jpg"
+    },
+    "engine": "nunjucks",
+    "engineOptions": {
+        "templatePath": "templates/template.md.njk",
+        "rootHtmlTemplate": "templates/wrapper.html.njk"
+    },
+    "files": [
+        {
+            "filename": "Kishan__nunjucks__Preview-Markdown.md",
+            "engineData": {
+                "name": "Preview-Markdown.md",
+                "metadata": {
+                    "type": "markdown"
+                }
+            }
+        },
+        {
+            "filename": "Kishan__nunjucks__Preview-HTML.html",
+            "engineData": {
+                "name": "Preview-HTML.html",
+                "metadata": {
+                    "type": "html"
+                }
+            }
+        }
+    ],
+    "email": {
+        "to": "[email protected]",
+        "subject": "DoCSoc x Kishan"
+    },
+    "attachments": [
+        "./attachments/munch.jpg"
+    ]
+}

email/workspace/output/specified.brown.grasshopper/Kishan__nunjucks__Preview-HTML.html

@@ -0,0 +1,26 @@
+<!-- DoCSoc Mail Merge Wrapper - used to wrap results rendered from Markdown -->
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8">
+		<meta name="viewport" content="width=device-width, initial-scale=1.0">
+	</head>
+	<body>
+		<p>Dear Kishan,</p>
+<p>I hope you are well.</p>
+<p>If you are seeing this email, it means that the new mail merge tool is working as expected.</p>
+<p>For it was this email you see, that was sent by complete mail merge pipeline.</p>
+<p>Of course, some things are still missing, namely:</p>
+<ul>
+<li>Attachments</li>
+<li>Crash-proofing so you don't double send emails</li>
+<li>A nice CLI</li>
+<li>Docs</li>
+</ul>
+<p>But it does work!</p>
+<p>Kind regards,<br>
+Some TypeScript code on behalf of Kishan Sambhi (he/him)<br>
+DoCSoc Vice President</p>
+
+	</body>
+</html>

email/workspace/output/specified.brown.grasshopper/Kishan__nunjucks__Preview-Markdown.md

@@ -0,0 +1,19 @@
+Dear Kishan,
+
+I hope you are well.
+
+If you are seeing this email, it means that the new mail merge tool is working as expected.
+
+For it was this email you see, that was sent by complete mail merge pipeline.
+
+Of course, some things are still missing, namely:
+- Attachments
+- Crash-proofing so you don't double send emails
+- A nice CLI
+- Docs
+
+But it does work!
+
+Kind regards,
+Some TypeScript code on behalf of Kishan Sambhi (he/him)
+DoCSoc Vice President