feat(contented): add image processing

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,