feat(contented): add image processing (#634)

#### What this PR does / why we need it:

Add images support for contented.

Image commonly used in Markdown is supported but with some caveats.
Contented being a prose-bundler is designed to bundle prose such that it
is portable and can be deployed to different sites or domains. This
makes it difficult to support images that are not bundled together with
the prose. To get around this, all local images are embedded into the
Markdown file as base64 encoded strings. Remote images are left as is.

README.md

@@ -1,7 +1,7 @@
 # Contented
 
-[Contented](https://contented.dev) is a Markdown-based bundler for your documentation with pipeline driven
-authoring-oriented workflow to encourage developer authoring within its contextual Git repository.
+[Contented](https://contented.dev) is a prose bundler for your documentation with pipeline driven
+authoring-oriented workflow to encourage developers authoring within its contextual Git repository.
 
 With a headless design of 1 config file `contented.config.mjs`, developers can start writing
 their [markdown content](./04-markdown.md) and preview it on their localhost `contented generate --watch`.
@@ -15,7 +15,7 @@ checks it is compilable and presentable.
 By encouraging authoring next to the source (in the same git repo), developers can contextually document changes as they
 develop. All domain-specific changes will go into the `main` branch with one Git Pull Request.
 
-With `contented build`, you can compile your markdown into sources `index.js` and `*.json`. That output
+With `contented build`, you can compile your prose into sources `index.js` and `*.json`. That output
 into `./dist` to `npm publish` them into any registry of your choice, for you can
 easily `npm i @your-scope/your-npm-package` and use the processed content on any of your downstream sites. Easily
 pulling up-to-date content and prose from individual domain-specific repositories and re-presented. Think microservices,
@@ -30,7 +30,7 @@ naturally satisfies.
 
 ### Just Another SSG?
 
-**This is not a static site generator.** This is a markdown processor workflow with a built-in static site generator.
+**This is not a static site generator.** This is a prose processor workflow with a built-in static site generator.
 The outcome we're trying to achieve is
 this [@contentedjs/contented-example/dist](https://www.jsdelivr.com/package/npm/@contentedjs/contented-example)
 
@@ -51,12 +51,12 @@ Your docs can be anywhere as long as contented is configured to pick them up.
 repo/
 ├─ packages/**
 ├─ docs/
-│  ├─ 01:Title 1/*.md
-│  ├─ 02:Title 2/*.md
-│  ├─ 03:Title 3/
-│  │  ├─ 01:Subtitle 1/*.md
-│  │  ├─ 02:overview.md
-│  │  └─ 03:faq.md
+│  ├─ 01-Title 1/*.md
+│  ├─ 02-Title 2/*.md
+│  ├─ 03-Title 3/
+│  │  ├─ 01-Subtitle 1/*.md
+│  │  ├─ 02-overview.md
+│  │  └─ 03-faq.md
 │  └─ package.json
 ├─ contented.config.mjs
 ├─ package.json

packages/contented-example/docs/04-markdown.md

@@ -330,3 +330,34 @@ const b = 2;
 
 ::::
 ````
+
+## Images
+
+Image commonly used in Markdown is supported but with some caveats.
+Contented being a prose-bundler is designed to bundle prose such that it is portable and can be deployed to different
+sites or domains.
+This makes it difficult to support images that are not bundled together with the prose.
+To get around this, all local images are embedded into the Markdown file as base64 encoded strings.
+Remote images are left as is.
+
+> You can inspect this HTML page to see how the images are embedded.
+
+:::div{.admonitions.yellow}
+
+Always be careful with user input. For example, it’s possible to hide JavaScript inside images (such as GIFs, WebPs, and
+SVGs). User provided images open you up to a cross-site scripting (XSS) attack.
+
+If you’re using Contented to render user-provided Markdown, you should disable images by default and only enable them
+when you trust the source. Contented designed to be used for developer authoring where the source is trusted and XSS
+being the least of your worries since the developer (having control of source code) can already inject arbitrary
+JavaScript into the page without needing to go through this lengthy process.
+
+:::
+
+![local-embedded-image.png](local-embedded-image.png)
+![placehold.co](https://placehold.co/1500x300.png?text=Remote%20Loaded%20Image)
+
+```markdown
+![local-embedded-image.png](local-embedded-image.png)
+![placehold.co](https://placehold.co/1500x300.png?text=Remote%20Loaded%20Image)
+```

packages/contented-pipeline-md/package.json

@@ -56,6 +56,7 @@
     "rehype-slug": "^5.1.0",
     "rehype-stringify": "^9.0.4",
     "remark-directive": "^2.0.1",
+    "remark-embed-images": "^4.0.0",
     "remark-frontmatter": "^4.0.1",
     "remark-gfm": "^3.0.1",
     "remark-parse": "^10.0.2",

packages/contented-pipeline-md/src/UnifiedProcessor.ts

@@ -4,6 +4,7 @@ import rehypeExternalLinks from 'rehype-external-links';
 import rehypeSlug from 'rehype-slug';
 import rehypeStringify from 'rehype-stringify';
 import remarkDirective from 'remark-directive';
+import remarkEmbedImages from 'remark-embed-images';
 import remarkFrontmatter from 'remark-frontmatter';
 import remarkGfm from 'remark-gfm';
 import remarkParse from 'remark-parse';
@@ -41,6 +42,7 @@ export function initProcessor(processor: Processor, options?: UnifiedOptions): P
     .use(remarkGfm)
     .use(remarkFrontmatter)
     .use(remarkParse)
+    .use(remarkEmbedImages)
     .use(remarkLink)
     .use(remarkDirective)
     .use(remarkDirectiveRehypeCodeblockHeader)
@@ -90,6 +92,7 @@ export {
   remarkDirectiveRehype,
   remarkDirectiveRehypeCodeblockGroup,
   remarkDirectiveRehypeCodeblockHeader,
+  remarkEmbedImages,
   remarkFrontmatter,
   remarkFrontmatterCollect,
   remarkFrontmatterResolve,