Skip to content

Commit 2e26f95

Browse files
Gum-JoeGum-Joe
committed
Docs: Add documentation
1 parent 3b4d2dc commit 2e26f95

File tree

10 files changed

+214
-9
lines changed

10 files changed

+214
-9
lines changed

‎email/libmailmerge/src/previews/sidecarData.ts

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ export async function writeMetadata(
112112
}
113113
const metadataFile = getRecordPreviewPrefixForMetadata(record, fileNamer);
114114
logger.debug(`Writing metadata for ${fileNamer(record)} to ${metadataFile}`);
115-
await writeSidecarFile(previewsRoot, metadataFile, sidecarData);
115+
await writeSidecarFile(join(previewsRoot, metadataFile), sidecarData);
116116
return Promise.resolve();
117117
}
118118

@@ -165,12 +165,8 @@ export function getSidecarMetadata(
165165
/**
166166
* Write the sidecar metadata file for a record
167167
*/
168-
export async function writeSidecarFile(
169-
previewsRoot: string,
170-
metadataFile: string,
171-
sidecar: SidecarData,
172-
) {
173-
await fs.writeFile(join(previewsRoot, metadataFile), JSON.stringify(sidecar, null, 4));
168+
export async function writeSidecarFile(metadataFilePath: string, sidecar: SidecarData) {
169+
await fs.writeFile(metadataFilePath, JSON.stringify(sidecar, null, 4));
174170
}
175171

176172
/**

‎email/mailmerge-cli/README.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,38 @@
11
# mailmerge-cli
22

3+
## Quick start
4+
5+
1. Run `npm install` from the root of the repo
6+
2. Run `npm run build` in this folder (`email/mailmerge-cli`)
7+
3. Run `npm link` in this folder - this adds `docsoc-mailmerge` to your path
8+
4. In a blank directory somewhere (known as the "mailmerge workspace"), create these folders & files:
9+
1. `./data/names.csv` - CSV file with at the minimum `email` & `subject` columns
10+
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)
11+
3. `./templates/wrapped.html.njk`, a HTML wrapper for the email (use the contents of `/email/workspace/wrapper.html.njk`)
12+
5. Run `docsoc-mailmerge generate nunjucks --help` and read the help text
13+
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>`
14+
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
15+
2. The HTML files, which is what is actually sent, can be regenerated after edting the markdown files with `regenerate` command (see below)
16+
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.
17+
7. Edit the generated markdown files - this allows you to edit the emails
18+
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.
19+
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>`.
20+
1. NOTE: Send does not run `regenerate`, so if you edited any markdown files ensure you ran `regenerate` before running `send`
21+
10. Done! Sent email previews will be moved to `./output/<runname>/sent` to prevent double sending if the send is stopped halfway through.
22+
23+
### Attachments
24+
25+
I recommend placing attachments in an `attachments` folder.
26+
27+
2 ways to add attachments:
28+
29+
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
30+
1. Use multiple columns e.g. `attachment1`, `attachment2` for multiple attachments
31+
2. When you run `generate` you will be asked which columns to use for attachments
32+
3. To edit which attachment to use ater `generate`, edit the JSON metadata files.
33+
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`.
34+
1. Note that if you pass the CLI option, any info about attachments in the CSV is ignored.
35+
336
This library was generated with [Nx](https://nx.dev).
437

538
## Building

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -190,5 +190,5 @@ export default async function generatePreviews(opts: CliOptions) {
190190
}),
191191
);
192192

193-
logger.info("Done! Review previews and then send.");
193+
logger.info(`Done! Review previews at ${previewsRoot} and then send.`);
194194
}

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ export async function rerenderPreviews(directory: string) {
5555
);
5656

5757
logger.info(`Updating sidecar metadata for ${name} at ${sidecar.$originalFilepath}...`);
58-
await writeSidecarFile(directory, sidecar.$originalFilepath, sidecar);
58+
await writeSidecarFile(sidecar.$originalFilepath, sidecar);
5959

6060
logger.info(`Finished rerendering ${name}`);
6161
}

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

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
{
2+
"name": "Kishan",
3+
"record": {
4+
"name": "Kishan",
5+
"email": "[email protected]",
6+
"subject": "DoCSoc x Kishan",
7+
"attachment1": "./attachments/DoCSoc Sponsorship Proposal 24-25.pdf",
8+
"attachment2": "./attachments/munch.jpg"
9+
},
10+
"engine": "nunjucks",
11+
"engineOptions": {
12+
"templatePath": "templates/template.md.njk",
13+
"rootHtmlTemplate": "templates/wrapper.html.njk"
14+
},
15+
"files": [
16+
{
17+
"filename": "Kishan__nunjucks__Preview-Markdown.md",
18+
"engineData": {
19+
"name": "Preview-Markdown.md",
20+
"metadata": {
21+
"type": "markdown"
22+
}
23+
}
24+
},
25+
{
26+
"filename": "Kishan__nunjucks__Preview-HTML.html",
27+
"engineData": {
28+
"name": "Preview-HTML.html",
29+
"metadata": {
30+
"type": "html"
31+
}
32+
}
33+
}
34+
],
35+
"email": {
36+
"to": "[email protected]",
37+
"subject": "DoCSoc x Kishan"
38+
},
39+
"attachments": [
40+
"./attachments/munch.jpg"
41+
],
42+
"$originalFilepath": "output/slight.rose.opossum/Kishan-metadata.json"
43+
}

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

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
<!-- DoCSoc Mail Merge Wrapper - used to wrap results rendered from Markdown -->
2+
<!DOCTYPE html>
3+
<html lang="en">
4+
<head>
5+
<meta charset="UTF-8">
6+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
7+
</head>
8+
<body>
9+
<p>Dear Kishan,</p>
10+
<p>I hope you are well. Do you like the photo I sent?</p>
11+
<p>If you are seeing this email, it means that the new mail merge tool is working as expected.</p>
12+
<p>For it was this email you see, that was sent by complete mail merge pipeline.</p>
13+
<p>Of course, some things are still missing, namely:</p>
14+
<ul>
15+
<li>Attachments</li>
16+
<li>Crash-proofing so you don't double send emails</li>
17+
<li>A nice CLI</li>
18+
<li>Docs</li>
19+
</ul>
20+
<p>But it does work!</p>
21+
<p>Kind regards,<br>
22+
Some TypeScript code on behalf of Kishan Sambhi (he/him)<br>
23+
DoCSoc Vice President</p>
24+
25+
</body>
26+
</html>

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

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
Dear Kishan,
2+
3+
I hope you are well. Do you like the photo I sent?
4+
5+
If you are seeing this email, it means that the new mail merge tool is working as expected.
6+
7+
For it was this email you see, that was sent by complete mail merge pipeline.
8+
9+
Of course, some things are still missing, namely:
10+
11+
- Attachments
12+
- Crash-proofing so you don't double send emails
13+
- A nice CLI
14+
- Docs
15+
16+
But it does work!
17+
18+
Kind regards,
19+
Some TypeScript code on behalf of Kishan Sambhi (he/him)
20+
DoCSoc Vice President

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

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
{
2+
"name": "Kishan",
3+
"record": {
4+
"name": "Kishan",
5+
"email": "[email protected]",
6+
"subject": "DoCSoc x Kishan",
7+
"attachment1": "./attachments/DoCSoc Sponsorship Proposal 24-25.pdf",
8+
"attachment2": "./attachments/munch.jpg"
9+
},
10+
"engine": "nunjucks",
11+
"engineOptions": {
12+
"templatePath": "templates/template.md.njk",
13+
"rootHtmlTemplate": "templates/wrapper.html.njk"
14+
},
15+
"files": [
16+
{
17+
"filename": "Kishan__nunjucks__Preview-Markdown.md",
18+
"engineData": {
19+
"name": "Preview-Markdown.md",
20+
"metadata": {
21+
"type": "markdown"
22+
}
23+
}
24+
},
25+
{
26+
"filename": "Kishan__nunjucks__Preview-HTML.html",
27+
"engineData": {
28+
"name": "Preview-HTML.html",
29+
"metadata": {
30+
"type": "html"
31+
}
32+
}
33+
}
34+
],
35+
"email": {
36+
"to": "[email protected]",
37+
"subject": "DoCSoc x Kishan"
38+
},
39+
"attachments": [
40+
"./attachments/munch.jpg"
41+
]
42+
}

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

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
<!-- DoCSoc Mail Merge Wrapper - used to wrap results rendered from Markdown -->
2+
<!DOCTYPE html>
3+
<html lang="en">
4+
<head>
5+
<meta charset="UTF-8">
6+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
7+
</head>
8+
<body>
9+
<p>Dear Kishan,</p>
10+
<p>I hope you are well.</p>
11+
<p>If you are seeing this email, it means that the new mail merge tool is working as expected.</p>
12+
<p>For it was this email you see, that was sent by complete mail merge pipeline.</p>
13+
<p>Of course, some things are still missing, namely:</p>
14+
<ul>
15+
<li>Attachments</li>
16+
<li>Crash-proofing so you don't double send emails</li>
17+
<li>A nice CLI</li>
18+
<li>Docs</li>
19+
</ul>
20+
<p>But it does work!</p>
21+
<p>Kind regards,<br>
22+
Some TypeScript code on behalf of Kishan Sambhi (he/him)<br>
23+
DoCSoc Vice President</p>
24+
25+
</body>
26+
</html>

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

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
Dear Kishan,
2+
3+
I hope you are well.
4+
5+
If you are seeing this email, it means that the new mail merge tool is working as expected.
6+
7+
For it was this email you see, that was sent by complete mail merge pipeline.
8+
9+
Of course, some things are still missing, namely:
10+
- Attachments
11+
- Crash-proofing so you don't double send emails
12+
- A nice CLI
13+
- Docs
14+
15+
But it does work!
16+
17+
Kind regards,
18+
Some TypeScript code on behalf of Kishan Sambhi (he/him)
19+
DoCSoc Vice President

0 commit comments

Comments
 (0)