@mzebley/mark-down 1.0.0 → 1.1.0

package/README.md

@@ -9,11 +9,12 @@ This package provides the framework-agnostic `SnippetClient` and supporting type
 2. [Quick start](#quick-start)
 3. [Client options](#client-options)
 4. [Working with snippets](#working-with-snippets)
-5. [SSR and custom fetchers](#ssr-and-custom-fetchers)
+5. [SSR and custom fetch functions](#ssr-and-custom-fetch-functions)
 6. [Static sites / CDN usage](#static-sites--cdn-usage)
-7. [Testing & type safety](#testing--type-safety)
-8. [Related packages](#related-packages)
-9. [Roadmap](#roadmap)
+7. [Zero-build inline mode](#zero-build-inline-mode)
+8. [Testing & type safety](#testing--type-safety)
+9. [Related packages](#related-packages)
+10. [Roadmap](#roadmap)
 
 ## Installation
 
@@ -37,7 +38,7 @@ const client = new SnippetClient({
 const hero = await client.get("getting-started-welcome");
 const components = await client.listByType("component");
 
-console.log(hero?.title);
+console.log(hero.title);
 ```
 
 The client lazily loads the manifest when first needed, then fetches Markdown files on demand. Results are cached for the lifetime of the client instance.
@@ -46,25 +47,30 @@ The client lazily loads the manifest when first needed, then fetches Markdown fi
 
 `SnippetClient` accepts a single configuration object:
 
-- **`manifest`** (`string | ManifestEntry[] | () => Promise<ManifestEntry[]>`) – where to load the manifest. Pass a URL (default), an in-memory array, or an async factory for advanced scenarios.
-- **`fetcher`** (`(input, init) => Promise<Response>`) – provide a custom fetch implementation. Useful for SSR environments or when using libraries like Axios.
-- **`markdownRenderer`** – a `(markdown: string) => string | Promise<string>` function. Override to swap the default `marked` renderer for something like `remark` or a bespoke pipeline.
-- **`resolveSnippetPath`** – map manifest entries to final URLs. Override when static assets live in a CDN or custom folder.
+- **`manifest`** (`string | SnippetMeta[] | () => Promise<SnippetMeta[]>`) – where to load the manifest. Provide a URL, an in-memory array, or an async factory.
+- **`base`** (`string`) – optional base path prepended to relative snippet paths. The client infers the directory from the manifest URL when omitted.
+- **`fetch`** (`(url: string) => Promise<Response | string>`) – inject a custom fetch implementation. Use this for SSR, testing, or advanced caching.
+- **`frontMatter`** (`boolean`, default `true`) – toggle YAML front-matter parsing.
+- **`cache`** (`boolean`, default `true`) – enable or disable per-snippet and manifest memoisation.
+- **`verbose`** (`boolean`) – log helpful warnings (for example, slug mismatches) during development.
+- **`render`** (`(markdown: string) => string | Promise<string>`) – override the default `marked` renderer when you need custom HTML output.
 
-All options are optional except `manifest`.
+All options are optional except `manifest`. Results are rendered with `marked` by default; override at the application level if you need a different Markdown pipeline.
 
 ## Working with snippets
 
 Commonly used APIs:
 
-- `client.get(slug)` – fetch a single snippet. Returns `Promise<Snippet | undefined>`.
-- `client.list(filterOrOptions)` – list snippets using predicates, offsets, and limits.
-- `client.listByType(type, options?)` – filter by `type`.
-- `client.listByGroup(group, options?)` – filter based on the folder-derived `group`.
+- `client.get(slug)` – fetch a single snippet. Throws `SnippetNotFoundError` if the manifest does not include the slug.
+- `client.listAll()` – return a copy of every manifest entry.
+- `client.listByType(type)` / `client.listByGroup(group)` – targeted manifest filters.
+- `client.search({ type, group, tags, tagsMode })` – multi-field search helper with tag matching.
+- `client.getHtml(slug)` – convenience wrapper that resolves directly to HTML.
+- `client.invalidate()` / `client.invalidateSlug(slug)` – clear caches to force refetching.
 
-Metadata is preserved exactly as declared in front matter. Standard keys (`slug`, `title`, etc.) are copied onto `SnippetMeta` and everything else is available through the `extra` bag so you can access custom fields like `snippet.extra.ctaLabel`.
+Metadata is preserved exactly as declared in front matter. Standard keys (`slug`, `title`, etc.) are copied onto `SnippetMeta`, additional properties live inside `extra`, and the resolved `Snippet` includes both rendered HTML and an optional `raw` Markdown string (without front matter) for advanced use cases.
 
-## SSR and custom fetchers
+## SSR and custom fetch functions
 
 The runtime runs in browsers, Node.js, or edge runtimes. For server-side rendering:
 
@@ -74,11 +80,16 @@ import { SnippetClient } from "@mzebley/mark-down";
 
 const client = new SnippetClient({
   manifest: () => import("./snippets-index.json"),
-  fetcher: (input, init) => fetch(input as string, init),
+  fetch: (url) => fetch(url).then((response) => {
+    if (!response.ok) {
+      throw new Error(`Request failed with status ${response.status}`);
+    }
+    return response;
+  }),
 });
 ```
 
-You can also pre-seed snippets by passing an array to `manifest` to avoid network requests entirely.
+You can also pre-seed snippets by passing an array to `manifest` to avoid network requests entirely. When `cache` is disabled the client re-fetches both manifest and snippet payloads on every request.
 
 ## Static sites / CDN usage
 
@@ -96,10 +107,112 @@ Need to run mark↓ inside a plain `<script type="module">` context? Use the pre
 
 As long as you host `snippets-index.json` (generated by the CLI) alongside your static assets, this bundle works without any additional tooling or manual Buffer shims.
 
+## Zero-build inline mode
+
+### Introduction
+
+Need Markdown inside plain HTML without a manifest, build step, or Node runtime? mark↓ ships a lightweight inline helper that scans the DOM for raw Markdown, renders it with the same `marked` pipeline used by `SnippetClient`, and progressively enhances the page. Content stays inside the HTML you ship, so crawlers and no-JS users can still read the raw Markdown even before JavaScript runs.
+
+### Installation
+
+Install the core package as usual:
+
+```bash
+npm install @mzebley/mark-down
+```
+
+- **Bundlers / ESM:** import the inline helper directly.
+
+  ```ts
+  import { enhanceInlineMarkdown } from "@mzebley/mark-down/inline";
+  ```
+
+- **Static `<script>` usage:** include the prebuilt UMD bundle that exposes `window.markDownInline`.
+
+  ```html
+  <script src="/node_modules/@mzebley/mark-down/dist/mark-down-inline.umd.js"></script>
+  <script>
+    document.addEventListener("DOMContentLoaded", () => {
+      window.markDownInline.enhanceInlineMarkdown();
+    });
+  </script>
+  ```
+
+Host the UMD file yourself or load it from a CDN—no build tooling required.
+
+### Basic usage (happy path)
+
+Write plain Markdown directly in your HTML. The helper finds `[data-markdown]` blocks by default.
+
+```html
+<div data-markdown>
+# Hello
+
+This is inline markdown with no build step.
+</div>
+
+<script src="path/to/mark-down-inline.umd.js"></script>
+<script>
+  document.addEventListener("DOMContentLoaded", function () {
+    window.markDownInline.enhanceInlineMarkdown();
+  });
+</script>
+```
+
+The Markdown text remains in the DOM for SEO while JavaScript enhances it to semantic HTML for users.
+
+### Advanced usage (power path with front matter)
+
+You can optionally prepend YAML front matter to provide metadata for each block. Fields are parsed with the same utilities used by the manifest flow.
+
+```html
+<div data-markdown>
+---
+slug: intro
+title: Introduction
+tags: [hero]
+variant: lead
+---
+
+# Introduction
+
+This block has metadata.
+</div>
+```
+
+- `slug` → sets `id="intro"` if no ID exists and `data-slug="intro"`, allowing deep links.
+- `title` → stored in `data-title` for TOC/index generation.
+- `tags` → serialized to `data-tags="hero"` (comma-separated when multiple) for light-weight client-side filtering.
+- `variant` → adds a class like `md-block--lead` so you can theme specific sections.
+
+You still get fully rendered HTML, but additional attributes unlock progressive enhancement such as TOCs or custom styling.
+
+### Options
+
+Configure the helper per page:
+
+```ts
+enhanceInlineMarkdown({
+  selector?: string; // defaults to "[data-markdown]"
+  processFrontMatter?: boolean; // defaults to true
+  applyMetaToDom?: boolean; // defaults to true
+});
+```
+
+- Use `selector` to target different attributes or classes.
+- Disable `processFrontMatter` when the block contains literal `---` fences that should stay visible.
+- Set `applyMetaToDom` to `false` if you only care about rendered HTML and not DOM metadata.
+
+### SEO & progressive enhancement
+
+- Raw Markdown lives directly in your HTML, so crawlers can index the text before scripts execute.
+- Users without JavaScript still see readable Markdown; JavaScript simply upgrades it to semantic HTML, adds IDs, and decorates DOM attributes for richer UX.
+- This inline mode is ideal for small/medium static pages or marketing sites. Larger doc sites should continue using the manifest-driven snippet system for better caching and composition.
+
 ## Testing & type safety
 
 - Use `SnippetMeta` and `Snippet` TypeScript types to describe props and state in your application.
-- Mock the client by providing a manifest array or by stubbing the `fetcher` function.
+- Mock the client by providing a manifest array or by stubbing the `fetch` option.
 - Run the workspace tests with `npm run test -- core` to exercise Vitest suites that cover caching, filtering, and Markdown conversion.
 
 ## Related packages

package/package.json

@@ -1,10 +1,8 @@
 {
   "name": "@mzebley/mark-down",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "mark↓ core runtime and shared utilities",
   "type": "module",
-  "main": "dist/index.cjs",
-  "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "publishConfig": {
     "access": "public"
@@ -12,17 +10,23 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs"
+      "import": "./dist/index.js"
     },
     "./slug": {
       "types": "./dist/slug.d.ts",
-      "import": "./dist/slug.mjs",
-      "require": "./dist/slug.cjs"
+      "import": "./dist/slug.js"
     },
     "./browser": {
       "types": "./dist/browser.d.ts",
       "import": "./dist/browser.js"
+    },
+    "./inline": {
+      "types": "./dist/inline.d.ts",
+      "import": "./dist/inline.js"
+    },
+    "./angular": {
+      "types": "./dist/angular/index.d.ts",
+      "import": "./dist/angular/index.js"
     }
   },
   "scripts": {
@@ -30,7 +34,8 @@
     "dev": "tsup --config tsup.config.ts --watch"
   },
   "dependencies": {
-    "gray-matter": "^4.0.3",
-    "marked": "^11.1.0"
-  }
+    "marked": "^11.1.0",
+    "yaml": "^2.4.1"
+  },
+  "sideEffects": false
 }

package/src/angular/index.ts

@@ -0,0 +1,47 @@
+import { Inject, Injectable, InjectionToken, Provider } from "@angular/core";
+import { from, map, Observable, shareReplay } from "rxjs";
+import { SnippetClient } from "../snippet-client";
+import type { Snippet, SnippetClientOptions, SnippetMeta } from "../types";
+
+export const SNIPPET_CLIENT = new InjectionToken<SnippetClient>("@mzebley/mark-down/SNIPPET_CLIENT");
+export const SNIPPET_CLIENT_OPTIONS = new InjectionToken<SnippetClientOptions>(
+  "@mzebley/mark-down/SNIPPET_CLIENT_OPTIONS"
+);
+
+export function provideSnippetClient(options: SnippetClientOptions): Provider[] {
+  return [
+    { provide: SNIPPET_CLIENT_OPTIONS, useValue: options },
+    {
+      provide: SNIPPET_CLIENT,
+      useFactory: (opts: SnippetClientOptions) => new SnippetClient(opts),
+      deps: [SNIPPET_CLIENT_OPTIONS]
+    }
+  ];
+}
+
+@Injectable({ providedIn: "root" })
+export class MarkdownSnippetService {
+  constructor(@Inject(SNIPPET_CLIENT) private readonly client: SnippetClient) {}
+
+  get(slug: string): Observable<Snippet> {
+    return from(this.client.get(slug)).pipe(shareReplay({ bufferSize: 1, refCount: true }));
+  }
+
+  listAll(): Observable<SnippetMeta[]> {
+    return from(this.client.listAll()).pipe(shareReplay({ bufferSize: 1, refCount: true }));
+  }
+
+  listByGroup(group: string): Observable<SnippetMeta[]> {
+    return from(this.client.listByGroup(group)).pipe(shareReplay({ bufferSize: 1, refCount: true }));
+  }
+
+  listByType(type: string): Observable<SnippetMeta[]> {
+    return from(this.client.listByType(type)).pipe(shareReplay({ bufferSize: 1, refCount: true }));
+  }
+
+  html(slug: string): Observable<string> {
+    return this.get(slug).pipe(map((snippet) => snippet.html));
+  }
+}
+
+export type { Snippet, SnippetClientOptions, SnippetMeta } from "../types";

package/src/errors.ts

@@ -0,0 +1,19 @@
+export class SnippetNotFoundError extends Error {
+  readonly slug: string;
+
+  constructor(slug: string) {
+    super(`Snippet with slug '${slug}' was not found in the manifest.`);
+    this.name = "SnippetNotFoundError";
+    this.slug = slug;
+  }
+}
+
+export class ManifestLoadError extends Error {
+  readonly cause?: unknown;
+
+  constructor(message: string, cause?: unknown) {
+    super(message);
+    this.name = "ManifestLoadError";
+    this.cause = cause instanceof Error ? cause : cause ? new Error(String(cause)) : undefined;
+  }
+}

package/src/front-matter.ts

@@ -0,0 +1,111 @@
+import { parse as parseYaml } from "yaml";
+import { ManifestLoadError } from "./errors";
+import type { SnippetMeta } from "./types";
+
+export interface FrontMatterResult {
+  content: string;
+  meta: Partial<SnippetMeta>;
+  extra: Record<string, unknown>;
+  slug?: string;
+  hasFrontMatter: boolean;
+}
+
+const FRONT_MATTER_PATTERN = /^(?:\uFEFF)?[ \t\r\n]*---\s*\r?\n([\s\S]*?)\r?\n---\s*\r?\n?/;
+
+export function parseFrontMatter(raw: string): FrontMatterResult {
+  const match = FRONT_MATTER_PATTERN.exec(raw);
+  if (!match) {
+    return { content: raw, meta: {}, extra: {}, hasFrontMatter: false };
+  }
+
+  const yamlSection = match[1];
+  let data: unknown;
+  try {
+    data = parseYaml(yamlSection) ?? {};
+  } catch (error) {
+    throw new ManifestLoadError("Failed to parse snippet front-matter.", error);
+  }
+
+  if (!isRecord(data)) {
+    return { content: raw.slice(match[0].length), meta: {}, extra: {}, hasFrontMatter: true };
+  }
+
+  const { known, extra } = splitFrontMatter(data);
+
+  return {
+    content: raw.slice(match[0].length),
+    meta: known.meta,
+    extra,
+    slug: known.slug,
+    hasFrontMatter: true
+  };
+}
+
+function splitFrontMatter(
+  data: Record<string, unknown>
+): { known: { meta: Partial<SnippetMeta>; slug?: string }; extra: Record<string, unknown> } {
+  const meta: Partial<SnippetMeta> = {};
+  const extra: Record<string, unknown> = {};
+  let slug: string | undefined;
+
+  for (const [key, value] of Object.entries(data)) {
+    switch (key) {
+      case "slug":
+        slug = typeof value === "string" ? value : undefined;
+        break;
+      case "title":
+        if (typeof value === "string") {
+          meta.title = value;
+        }
+        break;
+      case "type":
+        if (typeof value === "string") {
+          meta.type = value;
+        }
+        break;
+      case "order":
+        if (typeof value === "number") {
+          meta.order = value;
+        }
+        break;
+      case "tags":
+        meta.tags = normalizeTags(value);
+        break;
+      case "group":
+        if (typeof value === "string" || value === null) {
+          meta.group = value;
+        }
+        break;
+      case "draft":
+        if (typeof value === "boolean") {
+          meta.draft = value;
+        }
+        break;
+      default:
+        extra[key] = value;
+        break;
+    }
+  }
+
+  return { known: { meta, slug }, extra };
+}
+
+function normalizeTags(value: unknown): string[] | undefined {
+  if (!value) {
+    return undefined;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => String(item));
+  }
+  if (typeof value === "string") {
+    return value
+      .split(",")
+      .map((tag) => tag.trim())
+      .filter(Boolean);
+  }
+  return undefined;
+}
+
+function isRecord(candidate: unknown): candidate is Record<string, unknown> {
+  return Boolean(candidate) && typeof candidate === "object" && !Array.isArray(candidate);
+}

package/src/inline.ts

@@ -0,0 +1,80 @@
+import { parseFrontMatter, type FrontMatterResult } from "./front-matter";
+import { renderMarkdown } from "./markdown";
+
+export interface InlineMarkdownOptions {
+  selector?: string;
+  processFrontMatter?: boolean;
+  applyMetaToDom?: boolean;
+}
+
+const DEFAULT_SELECTOR = "[data-markdown]";
+
+export function enhanceInlineMarkdown(options: InlineMarkdownOptions = {}): void {
+  if (typeof document === "undefined") {
+    return;
+  }
+
+  const selector = options.selector ?? DEFAULT_SELECTOR;
+  const processFrontMatter = options.processFrontMatter !== false;
+  const applyMetaToDom = options.applyMetaToDom !== false;
+
+  const elements = Array.from(document.querySelectorAll<HTMLElement>(selector));
+  for (const element of elements) {
+    if (element.dataset.markdownProcessed === "true") {
+      continue;
+    }
+    processElement(element, { processFrontMatter, applyMetaToDom });
+  }
+}
+
+function processElement(
+  element: HTMLElement,
+  options: { processFrontMatter: boolean; applyMetaToDom: boolean }
+): void {
+  const raw = element.textContent ?? "";
+  let frontMatter: FrontMatterResult | undefined;
+
+  if (options.processFrontMatter) {
+    try {
+      frontMatter = parseFrontMatter(raw);
+    } catch (error) {
+      console.warn("[mark↓ inline] Failed to parse front matter for element:", error);
+      frontMatter = undefined;
+    }
+  }
+
+  const body = frontMatter?.content ?? raw;
+  const html = renderMarkdown(body);
+
+  element.innerHTML = html;
+  element.dataset.markdownProcessed = "true";
+
+  if (options.applyMetaToDom && frontMatter?.hasFrontMatter) {
+    applyMetaAttributes(element, frontMatter);
+  }
+}
+
+function applyMetaAttributes(element: HTMLElement, frontMatter: FrontMatterResult): void {
+  const { slug, meta, extra } = frontMatter;
+
+  if (slug) {
+    if (!element.id) {
+      element.id = slug;
+    }
+    element.dataset.slug = slug;
+  }
+
+  if (meta.title) {
+    element.dataset.title = meta.title;
+  }
+
+  if (meta.tags?.length) {
+    element.dataset.tags = meta.tags.join(",");
+  }
+
+  const variant = typeof extra.variant === "string" ? extra.variant.trim() : "";
+  if (variant) {
+    element.classList.add(`md-block--${variant}`);
+  }
+
+}

package/src/markdown.ts

@@ -0,0 +1,5 @@
+import { marked } from "marked";
+
+export function renderMarkdown(markdown: string): string {
+  return marked.parse(markdown);
+}