@dxj.jp/md-embed 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DXJ (https://dxj.jp)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# md-embed (`@dxj.jp/md-embed`)
+
+> **Live demo: [md-embed.dxj.jp](https://md-embed.dxj.jp)** — every block of prose on that page is Markdown in R2, rendered at request time by this package. Tested on real workerd via `@cloudflare/vitest-pool-workers`. The unscoped `md-embed` npm name is held by [DXJ](https://dxj.jp) and points here.
+
+Embed live Markdown into any HTML page at the edge.
+
+`md-embed` is a streaming shortcode renderer for Cloudflare Workers. Drop a custom element into your HTML:
+
+```html
+<md-embed src="docs/intro.md"></md-embed>
+```
+
+and the Worker resolves it at request time with HTMLRewriter — fetching the Markdown from R2, rendering it to clean HTML (`##` → `<h2>`, GFM tables, and more), and streaming it into place. Update the Markdown in R2 and every embedding page reflects it instantly, with no redeploy.
+
+## Why
+
+- **Live content**: Markdown lives in R2 and is edited by humans *and* AI agents. Provenance attributes (`data-md-etag`) make cache invalidation trivial.
+- **Streaming**: HTMLRewriter transforms the page as it streams — no full-page buffering.
+- **One tag**: the `<md-embed>` custom element is the whole integration surface.
+
+## Quickstart (Hono)
+
+```sh
+npm i @dxj.jp/md-embed
+```
+
+```ts
+import { Hono } from "hono";
+import { mdEmbed, r2Resolver } from "@dxj.jp/md-embed";
+
+type Env = { CONTENT: R2Bucket; ASSETS: Fetcher };
+
+const app = new Hono<{ Bindings: Env }>();
+
+app.use(mdEmbed((env) => r2Resolver((env as Env).CONTENT)));
+app.get("*", (c) => c.env.ASSETS.fetch(c.req.raw));
+
+export default app;
+```
+
+Any `text/html` response passing through the middleware gets its `<md-embed>` elements resolved. Non-HTML responses are untouched.
+
+## API
+
+```ts
+render(markdown, options?)            // Markdown → HTML string (wrapped in <article class="prose">)
+r2Resolver(bucket, { prefix? })       // MarkdownResolver backed by an R2 bucket
+transform(response, resolver, opts?)  // stream-resolve <md-embed> in a Response
+mdEmbed(env => resolver, opts?)       // Hono-compatible middleware (no hono dependency)
+```
+
+### Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `wrapperClass` | `"prose"` | Class on the `<article>` wrapper; `null` disables wrapping |
+| `markedOptions` | GFM on | Forwarded to [marked](https://marked.js.org) (`async` is always forced to `false`) |
+| `tagName` | `"md-embed"` | Element to resolve (should contain a hyphen — custom-element convention) |
+| `allowSrc` | allow all | Allowlist gate for `src` values; rejected embeds get `data-md-error="not-allowed"` |
+
+### Element contract
+
+The `<md-embed>` element **stays in the DOM** after rendering — its inner content is replaced and attributes are stamped:
+
+| Attribute | Meaning |
+|---|---|
+| `rendered` | Present when server-side rendering succeeded (a future client-side Web Component skips hydration when set) |
+| `data-md-src` | The resolved source path |
+| `data-md-etag` | Version identifier from the resolver (R2 `httpEtag`) |
+| `data-md-error` | `missing-src` / `not-allowed` / `not-found` / `resolver-error` / `render-error` when rendering failed (element and its fallback content left as-is) |
+
+Elements that already carry `rendered` are skipped, so layered rendering (edge cache → origin) is safe. Failures are contained per element — one broken embed never breaks the page.
+
+**Closing tag required.** HTML has no self-closing custom elements: `<md-embed src="…" />` is parsed as an open tag and will swallow everything up to its parent's close. Always write `<md-embed src="…"></md-embed>`.
+
+**Headers.** Transformed responses have upstream `ETag`, `Last-Modified`, and `Content-Length` stripped — those validators describe the original asset, not the composed page, and would let browsers revalidate into stale embeds.
+
+### Conventions
+
+- Raw Markdown should be reachable at a `.md` alias URL (serve `text/markdown` for the same path); content negotiation via `Accept` headers is treated as sugar on top, never the canonical route.
+
+## Security
+
+Rendered Markdown is **not sanitized** — embed only content you control (your own R2 bucket, your repo). Do not point a resolver at untrusted third-party input.
+
+The `src` attribute is a **server-side include surface**: the embedding HTML must be fully trusted too. Do not run the middleware over pages containing user-generated markup — anyone who can inject a tag can inline any object your resolver reaches (e.g. unpublished drafts). Use `allowSrc` to restrict resolvable sources, and note that `r2Resolver` treats keys as literals (no `../` traversal), but custom HTTP/filesystem resolvers must enforce that themselves.
+
+TypeScript consumers: `@cloudflare/workers-types` is an optional peer dependency — install it (or use `wrangler types`) so `R2Bucket` and friends resolve.
+
+## Development
+
+```sh
+pnpm install
+pnpm test    # vitest on real workerd (HTMLRewriter included)
+pnpm build   # tsc → dist/
+```
+
+## Roadmap
+
+- `0.1.0` — core (`render` / `r2Resolver` / `transform` / `mdEmbed`) — shipped, dogfooded on [md-embed.dxj.jp](https://md-embed.dxj.jp)
+- Cache API integration (ETag-keyed, stale-while-revalidate)
+- Client-side `<md-embed>` Web Component sharing this element contract
+- `llms.txt` generation from embedded sources
+
+## License
+
+MIT — made by [DXJ](https://dxj.jp)

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+import type { MarkedOptions } from "marked";
+import type { R2Bucket } from "@cloudflare/workers-types";
+export interface ResolvedMarkdown {
+    /** Raw Markdown source. */
+    markdown: string;
+    /** Opaque version identifier (e.g. R2 `httpEtag`). Emitted as `data-md-etag`. */
+    etag?: string;
+}
+/** Maps an `src` attribute value to Markdown content. Return null when the source does not exist. */
+export type MarkdownResolver = (src: string) => Promise<ResolvedMarkdown | null>;
+export interface MdEmbedOptions {
+    /** Class for the `<article>` wrapper around rendered output. `null` disables the wrapper. Default `"prose"`. */
+    wrapperClass?: string | null;
+    /** Options forwarded to `marked.parse`. GFM is enabled by default; `async` is always forced to `false`. */
+    markedOptions?: MarkedOptions;
+    /** Element tag to resolve. Should contain a hyphen (custom-element convention). Default `"md-embed"`. */
+    tagName?: string;
+    /** Allowlist gate for `src` values. Rejected elements get `data-md-error="not-allowed"`. */
+    allowSrc?: (src: string) => boolean;
+}
+/** Render Markdown to HTML (`##` → `<h2>`, GFM tables, etc.), wrapped for typography styling. */
+export declare function render(markdown: string, options?: MdEmbedOptions): string;
+/** Resolver backed by an R2 bucket. `src` attributes are used as object keys (with optional prefix). */
+export declare function r2Resolver(bucket: R2Bucket, opts?: {
+    prefix?: string;
+}): MarkdownResolver;
+/**
+ * Resolve every `<md-embed>` in an HTML response via HTMLRewriter (streaming —
+ * the page is never fully buffered). Non-HTML responses pass through untouched.
+ *
+ * Upstream validators (`ETag`, `Last-Modified`) and `Content-Length` are
+ * stripped from transformed responses: they describe the original asset, not
+ * the composed page, and would let clients revalidate into stale embeds —
+ * breaking the "update the Markdown, see it instantly" contract.
+ */
+export declare function transform(response: Response, resolve: MarkdownResolver, options?: MdEmbedOptions): Response;
+/**
+ * Hono-compatible middleware (no dependency on hono itself). Always takes a
+ * factory so bindings can be read from the per-request `env`:
+ *
+ *   app.use(mdEmbed<Env>(env => r2Resolver(env.CONTENT)))
+ *   app.use(mdEmbed(() => myStaticResolver))
+ */
+export declare function mdEmbed<E = unknown>(getResolver: (env: E) => MarkdownResolver, options?: MdEmbedOptions): (c: {
+    res: Response;
+    env: E;
+}, next: () => Promise<void>) => Promise<void>;

package/dist/index.js

@@ -0,0 +1,123 @@
+/**
+ * md-embed — streaming <md-embed> shortcode rendering for Cloudflare Workers.
+ *
+ * The <md-embed> element stays in the output DOM (custom-element semantics):
+ * its inner content is replaced with rendered HTML and provenance attributes
+ * are stamped on it, so a future client-side Web Component can skip hydration
+ * when `rendered` is present.
+ *
+ * Failures are contained per element: the element keeps its fallback content
+ * and gets a `data-md-error` attribute — one broken embed never breaks the page.
+ *
+ * Markdown is NOT sanitized — only embed content you control (e.g. your own
+ * R2 bucket). The embedding HTML must be fully trusted too: any markup
+ * injection on the page becomes a server-side include via the `src` attribute,
+ * so do not run this middleware over pages containing user-generated HTML
+ * (or restrict sources with `allowSrc`).
+ */
+import { marked } from "marked";
+const DEFAULT_TAG = "md-embed";
+const DEFAULT_WRAPPER_CLASS = "prose";
+const escapeAttr = (value) => value.replaceAll("&", "&amp;").replaceAll('"', "&quot;");
+/** Render Markdown to HTML (`##` → `<h2>`, GFM tables, etc.), wrapped for typography styling. */
+export function render(markdown, options = {}) {
+    const html = marked.parse(markdown, {
+        gfm: true,
+        ...options.markedOptions,
+        async: false,
+    });
+    const wrapperClass = options.wrapperClass === undefined ? DEFAULT_WRAPPER_CLASS : options.wrapperClass;
+    return wrapperClass === null
+        ? html
+        : `<article class="${escapeAttr(wrapperClass)}">${html}</article>`;
+}
+/** Resolver backed by an R2 bucket. `src` attributes are used as object keys (with optional prefix). */
+export function r2Resolver(bucket, opts = {}) {
+    return async (src) => {
+        const object = await bucket.get((opts.prefix ?? "") + src);
+        if (!object)
+            return null;
+        return { markdown: await object.text(), etag: object.httpEtag };
+    };
+}
+class MdEmbedHandler {
+    resolve;
+    options;
+    constructor(resolve, options) {
+        this.resolve = resolve;
+        this.options = options;
+    }
+    async element(el) {
+        if (el.getAttribute("rendered") !== null)
+            return; // already rendered upstream
+        const src = el.getAttribute("src");
+        if (!src) {
+            el.setAttribute("data-md-error", "missing-src");
+            return;
+        }
+        if (this.options.allowSrc && !this.options.allowSrc(src)) {
+            el.setAttribute("data-md-error", "not-allowed");
+            return;
+        }
+        let resolved;
+        try {
+            resolved = await this.resolve(src);
+        }
+        catch {
+            el.setAttribute("data-md-error", "resolver-error");
+            return;
+        }
+        if (!resolved) {
+            el.setAttribute("data-md-error", "not-found");
+            return;
+        }
+        let html;
+        try {
+            html = render(resolved.markdown, this.options);
+        }
+        catch {
+            el.setAttribute("data-md-error", "render-error");
+            return;
+        }
+        el.setInnerContent(html, { html: true });
+        el.setAttribute("rendered", "");
+        el.setAttribute("data-md-src", src);
+        if (resolved.etag)
+            el.setAttribute("data-md-etag", resolved.etag);
+    }
+}
+/**
+ * Resolve every `<md-embed>` in an HTML response via HTMLRewriter (streaming —
+ * the page is never fully buffered). Non-HTML responses pass through untouched.
+ *
+ * Upstream validators (`ETag`, `Last-Modified`) and `Content-Length` are
+ * stripped from transformed responses: they describe the original asset, not
+ * the composed page, and would let clients revalidate into stale embeds —
+ * breaking the "update the Markdown, see it instantly" contract.
+ */
+export function transform(response, resolve, options = {}) {
+    const contentType = (response.headers.get("content-type") ?? "").toLowerCase();
+    if (!contentType.includes("text/html"))
+        return response;
+    const transformed = new HTMLRewriter()
+        .on(options.tagName ?? DEFAULT_TAG, new MdEmbedHandler(resolve, options))
+        .transform(response);
+    const out = new Response(transformed.body, transformed);
+    out.headers.delete("etag");
+    out.headers.delete("last-modified");
+    out.headers.delete("content-length");
+    return out;
+}
+/**
+ * Hono-compatible middleware (no dependency on hono itself). Always takes a
+ * factory so bindings can be read from the per-request `env`:
+ *
+ *   app.use(mdEmbed<Env>(env => r2Resolver(env.CONTENT)))
+ *   app.use(mdEmbed(() => myStaticResolver))
+ */
+export function mdEmbed(getResolver, options = {}) {
+    return async (c, next) => {
+        await next();
+        c.res = transform(c.res, getResolver(c.env), options);
+    };
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@dxj.jp/md-embed",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Streaming <md-embed> shortcode renderer for Cloudflare Workers: embeds live, R2-backed Markdown into HTML via HTMLRewriter.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "markdown",
+    "cloudflare-workers",
+    "htmlrewriter",
+    "hono",
+    "shortcode",
+    "custom-element",
+    "md-embed",
+    "r2",
+    "edge"
+  ],
+  "author": "DXJ (https://dxj.jp)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kyutarou/md-embed.git"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "workerd",
+      "esbuild"
+    ]
+  },
+  "dependencies": {
+    "marked": "^18.0.6"
+  },
+  "peerDependencies": {
+    "@cloudflare/workers-types": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@cloudflare/workers-types": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "^0.18.4",
+    "@cloudflare/workers-types": "^5.20260712.1",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10",
+    "wrangler": "^4.110.0"
+  }
+}