framer-cms-markdown 0.0.1

package/src/libs/framer/framer-client.ts

@@ -0,0 +1,267 @@
+import {
+	connect,
+	type Collection,
+	type CollectionItem,
+	type CollectionItemInput,
+	type Field,
+	type FieldDataEntryInput,
+	type Framer,
+	type FieldDataEntry,
+} from "framer-api";
+
+export type FramerClientOptions = {
+	projectRef: string;
+	token: string;
+};
+
+export type FramerCollectionItemExport = {
+	id: string;
+	slug: string;
+	draft?: boolean;
+	fieldData: Record<string, unknown>;
+};
+
+function extractAssetUrl(value: unknown): string | undefined {
+	if (!value || typeof value !== "object") {
+		return undefined;
+	}
+
+	const record = value as Record<string, unknown>;
+	return typeof record.url === "string" ? record.url : undefined;
+}
+
+function extractIdOrString(value: unknown): string | undefined {
+	if (typeof value === "string") {
+		return value;
+	}
+
+	if (!value || typeof value !== "object") {
+		return undefined;
+	}
+
+	const record = value as Record<string, unknown>;
+	if (typeof record.id === "string") {
+		return record.id;
+	}
+
+	if (typeof record.name === "string") {
+		return record.name;
+	}
+
+	return undefined;
+}
+
+function normalizeFieldEntry(entry: FieldDataEntry): unknown {
+	switch (entry.type) {
+		case "boolean":
+		case "number":
+		case "string":
+		case "enum":
+		case "link":
+			return entry.value;
+		case "date":
+			return entry.value ?? undefined;
+		case "formattedText":
+			return typeof entry.value === "string" ? entry.value : undefined;
+		case "image":
+		case "file":
+			return extractAssetUrl(entry.value);
+		case "color":
+			return extractIdOrString(entry.value);
+		case "collectionReference":
+			return entry.value ?? undefined;
+		case "multiCollectionReference":
+			return Array.isArray(entry.value) ? entry.value : undefined;
+		default:
+			return undefined;
+	}
+}
+
+export function createFieldDataEntryInput(
+	field: Field,
+	value: unknown,
+	options: {
+		formattedTextContentType?: "auto" | "markdown" | "html";
+	} = {},
+): FieldDataEntryInput | undefined {
+	switch (field.type) {
+		case "boolean":
+			return typeof value === "boolean"
+				? { type: field.type, value }
+				: undefined;
+		case "number":
+			return typeof value === "number"
+				? { type: field.type, value }
+				: undefined;
+		case "string":
+			return typeof value === "string"
+				? { type: field.type, value }
+				: undefined;
+		case "formattedText":
+			return typeof value === "string"
+				? {
+						type: field.type,
+						value,
+						contentType: options.formattedTextContentType ?? "html",
+					}
+				: undefined;
+		case "enum":
+			return typeof value === "string"
+				? { type: field.type, value }
+				: undefined;
+		case "link":
+			return typeof value === "string"
+				? { type: field.type, value }
+				: undefined;
+		case "date":
+			return typeof value === "string" || typeof value === "number"
+				? { type: field.type, value: value as string | number }
+				: undefined;
+		case "collectionReference":
+			return typeof value === "string" || value === null
+				? { type: field.type, value: value as string | null }
+				: undefined;
+		case "multiCollectionReference":
+			return Array.isArray(value) &&
+				value.every((entry) => typeof entry === "string")
+				? { type: field.type, value: value as readonly string[] }
+				: undefined;
+		case "color":
+		case "file":
+		case "image":
+			return typeof value === "string" || value === null
+				? { type: field.type, value: value as string | null }
+				: undefined;
+		case "array":
+		case "divider":
+		case "unsupported":
+			return undefined;
+		default:
+			return undefined;
+	}
+}
+
+export class FramerClient {
+	private readonly projectRef: string;
+	private readonly token: string;
+	private framer: Framer | undefined;
+
+	constructor(options: FramerClientOptions) {
+		this.projectRef = options.projectRef;
+		this.token = options.token;
+	}
+
+	async connect(): Promise<void> {
+		if (!this.framer) {
+			this.framer = await connect(this.projectRef, this.token);
+		}
+	}
+
+	async disconnect(): Promise<void> {
+		if (this.framer) {
+			await this.framer.disconnect();
+			this.framer = undefined;
+		}
+	}
+
+	async getCollections(): Promise<Collection[]> {
+		return (await this.getFramer()).getCollections();
+	}
+
+	async resolveCollection(collectionRef: string): Promise<Collection> {
+		const collections = await this.getCollections();
+		const normalizedRef = collectionRef.trim().toLowerCase();
+		const match = collections.find((collection) => {
+			return (
+				collection.id.toLowerCase() === normalizedRef ||
+				collection.name.toLowerCase() === normalizedRef
+			);
+		});
+
+		if (!match) {
+			const available = collections
+				.map((collection) => `${collection.name} (${collection.id})`)
+				.join(", ");
+			throw new Error(
+				`Collection "${collectionRef}" was not found. Available collections: ${available || "none"}.`,
+			);
+		}
+
+		return match;
+	}
+
+	async getCollectionData(collectionRef: string): Promise<{
+		collection: Collection;
+		fields: Field[];
+		items: CollectionItem[];
+	}> {
+		const collection = await this.resolveCollection(collectionRef);
+		const fields = await collection.getFields();
+		const items = await collection.getItems();
+
+		return { collection, fields, items };
+	}
+
+	async getCollectionExportData(collectionRef: string): Promise<{
+		collection: Collection;
+		fields: Field[];
+		items: FramerCollectionItemExport[];
+	}> {
+		const { collection, fields, items } =
+			await this.getCollectionData(collectionRef);
+
+		return {
+			collection,
+			fields,
+			items: items.map((item) => this.toExportItem(item, fields)),
+		};
+	}
+
+	async upsertCollectionItems(
+		collection: Collection,
+		items: CollectionItemInput[],
+	): Promise<void> {
+		await collection.addItems(items);
+	}
+
+	private async getFramer(): Promise<Framer> {
+		await this.connect();
+		if (!this.framer) {
+			throw new Error("Failed to connect to Framer");
+		}
+
+		return this.framer;
+	}
+
+	private toExportItem(
+		item: CollectionItem,
+		fields: Field[],
+	): FramerCollectionItemExport {
+		const fieldData: Record<string, unknown> = {};
+
+		for (const field of fields) {
+			if (field.type === "divider") {
+				continue;
+			}
+
+			const entry = item.fieldData[field.id];
+			if (!entry) {
+				continue;
+			}
+
+			const value = normalizeFieldEntry(entry);
+			if (value === undefined) {
+				continue;
+			}
+
+			fieldData[field.name] = value;
+		}
+
+		return {
+			id: String(item.id),
+			slug: item.slug,
+			draft: item.draft,
+			fieldData,
+		};
+	}
+}

package/src/libs/framer/frontmatter.ts

@@ -0,0 +1,69 @@
+import yaml from "yaml";
+
+function normalizeYamlValue(value: unknown): unknown {
+	if (value instanceof Date) {
+		return value.toISOString();
+	}
+
+	if (Array.isArray(value)) {
+		return value.map(normalizeYamlValue);
+	}
+
+	if (value && typeof value === "object") {
+		const output: Record<string, unknown> = {};
+		for (const [key, nestedValue] of Object.entries(
+			value as Record<string, unknown>,
+		)) {
+			if (nestedValue !== undefined) {
+				output[key] = normalizeYamlValue(nestedValue);
+			}
+		}
+
+		return output;
+	}
+
+	return value;
+}
+
+export function toFrontmatter(data: Record<string, unknown>): string {
+	const filtered: Record<string, unknown> = {};
+
+	for (const [key, value] of Object.entries(data)) {
+		if (value === undefined) {
+			continue;
+		}
+
+		filtered[key] = normalizeYamlValue(value);
+	}
+
+	const rendered = yaml.stringify(filtered, {
+		lineWidth: 0,
+		singleQuote: true,
+	});
+
+	return `---\n${rendered.trimEnd()}\n---\n\n`;
+}
+
+export function parseFrontmatterDocument(content: string): {
+	data: Record<string, unknown>;
+	body: string;
+} {
+	const normalized = content.replace(/\r\n/g, "\n");
+	const match = normalized.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+
+	if (!match) {
+		return { data: {}, body: normalized };
+	}
+
+	const [, rawFrontmatter, rawBody] = match;
+	const parsed = yaml.parse(rawFrontmatter) as unknown;
+	const data =
+		parsed && typeof parsed === "object" && !Array.isArray(parsed)
+			? (parsed as Record<string, unknown>)
+			: {};
+
+	return {
+		data,
+		body: rawBody.replace(/^\n+/, ""),
+	};
+}

package/src/libs/framer/markdown.ts

@@ -0,0 +1,84 @@
+import rehypeParse from "rehype-parse";
+import rehypeRemark from "rehype-remark";
+import rehypeStringify from "rehype-stringify";
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import remarkRehype from "remark-rehype";
+import remarkStringify from "remark-stringify";
+import { unified } from "unified";
+
+const htmlToMarkdownProcessor = unified()
+	.use(rehypeParse, { fragment: true })
+	.use(rehypeRemark)
+	.use(remarkGfm, {
+		tablePipeAlign: true,
+		tableCellPadding: true,
+	})
+	.use(remarkStringify, {
+		bullet: "-",
+		emphasis: "_",
+		fences: true,
+		setext: false,
+	});
+
+const markdownToHtmlProcessor = unified()
+	.use(remarkParse)
+	.use(remarkGfm)
+	.use(remarkRehype)
+	.use(rehypeStringify, { closeSelfClosing: true });
+
+function normalizeFragment(markdown: string): string {
+	return markdown.trim().replace(/\n{3,}/g, "\n\n");
+}
+
+function stripMarkdownComments(markdown: string): string {
+	return markdown.replace(/<!--[\s\S]*?-->\s*/g, "").trim();
+}
+
+export async function htmlToMarkdown(html: string): Promise<string> {
+	const input = html.trim();
+	if (!input) {
+		return "";
+	}
+
+	const file = await htmlToMarkdownProcessor.process(input);
+	const markdown = normalizeFragment(String(file));
+	return markdown.length > 0 ? `${markdown}\n` : "";
+}
+
+export async function markdownToHtml(markdown: string): Promise<string> {
+	const input = stripMarkdownComments(markdown);
+	if (!input) {
+		return "";
+	}
+
+	const file = await markdownToHtmlProcessor.process(input);
+	return String(file).trim();
+}
+
+export function splitMarkdownIntoSections(markdown: string): string[] {
+	const normalized = markdown.replace(/\r\n/g, "\n").trim();
+	if (!normalized) {
+		return [];
+	}
+
+	const lines = normalized.split("\n");
+	const sections: string[] = [];
+	let current: string[] = [];
+
+	for (const line of lines) {
+		if (/^##\s+/.test(line) && current.length > 0) {
+			sections.push(current.join("\n").trim());
+			current = [line];
+			continue;
+		}
+
+		current.push(line);
+	}
+
+	if (current.length > 0) {
+		sections.push(current.join("\n").trim());
+	}
+
+	return sections.filter((section) => section.length > 0);
+}

package/src/markdown-to-framer/__tests__/import.spec.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "@jest/globals";
+import type { Field } from "framer-api";
+
+import {
+	buildCollectionItemInput,
+	resolveSectionHtmlFields,
+	type MarkdownDocument,
+} from "../import";
+
+function field(id: string, name: string, type: Field["type"]): Field {
+	return { id, name, type } as unknown as Field;
+}
+
+describe("markdown-to-framer import", () => {
+	it("maps metadata verbatim and rebuilds ordered section html fields", async () => {
+		const document: MarkdownDocument = {
+			path: "/tmp/example.md",
+			slug: "example-post",
+			metadata: {
+				Title: "Example Post",
+				Excerpt: "Short summary",
+			},
+			body: [
+				"Intro paragraph.",
+				"",
+				"## Second Section",
+				"",
+				"| A | B |",
+				"| --- | --- |",
+				"| 1 | 2 |",
+			].join("\n"),
+		};
+
+		const fields = [
+			field("title-id", "Title", "string"),
+			field("excerpt-id", "Excerpt", "string"),
+			field("s02-id", "Section 02 HTML", "formattedText"),
+			field("s01-id", "Section 01 HTML", "formattedText"),
+			field("s02-title-id", "Section 02 Title", "string"),
+			field("s01-title-id", "Section 01 Title", "string"),
+		];
+
+		expect(resolveSectionHtmlFields(fields).map((entry) => entry.name)).toEqual(
+			["Section 01 HTML", "Section 02 HTML"],
+		);
+
+		const item = await buildCollectionItemInput(
+			document,
+			fields,
+			{
+				markdown: "sections",
+				metadata: ["Title", "Excerpt"],
+			},
+			new Map(),
+		);
+
+		expect(item.slug).toBe("example-post");
+		expect(item.fieldData?.["title-id"]).toEqual({
+			type: "string",
+			value: "Example Post",
+		});
+		expect(item.fieldData?.["excerpt-id"]).toEqual({
+			type: "string",
+			value: "Short summary",
+		});
+		expect(item.fieldData?.["s01-id"]).toMatchObject({
+			type: "formattedText",
+			contentType: "html",
+		});
+		expect(item.fieldData?.["s02-id"]).toMatchObject({
+			type: "formattedText",
+			contentType: "html",
+		});
+		expect(item.fieldData?.["s01-title-id"]).toEqual({
+			type: "string",
+			value: "",
+		});
+		expect(item.fieldData?.["s02-title-id"]).toEqual({
+			type: "string",
+			value: "Second Section",
+		});
+		expect((item.fieldData?.["s01-id"] as { value: string }).value).toContain(
+			"<p>Intro paragraph.</p>",
+		);
+		expect((item.fieldData?.["s02-id"] as { value: string }).value).toContain(
+			"<table>",
+		);
+	});
+});

package/src/markdown-to-framer/__tests__/json-ld-faq.spec.ts

@@ -0,0 +1,116 @@
+import { markdownFaqToJsonLd } from "../json-ld-faq";
+
+describe("markdownFaqToJsonLdScript", () => {
+	it("returns null when no FAQ section exists", () => {
+		const markdown = `
+# Introduction
+
+Some content.
+
+## Features
+
+More content.
+`;
+
+		expect(markdownFaqToJsonLd(markdown)).toBeNull();
+	});
+
+	it("converts a FAQ section into JSON-LD", () => {
+		const markdown = `
+# Article
+
+Some text.
+
+## FAQ
+
+### Question 1?
+
+Answer 1.
+
+### Question 2?
+
+Answer 2.
+`;
+
+		const json = markdownFaqToJsonLd(markdown);
+
+		expect(json).not.toBeNull();
+
+		expect(json).toEqual({
+			"@context": "https://schema.org",
+			"@type": "FAQPage",
+			mainEntity: [
+				{
+					"@type": "Question",
+					name: "Question 1?",
+					acceptedAnswer: {
+						"@type": "Answer",
+						text: "Answer 1.",
+					},
+				},
+				{
+					"@type": "Question",
+					name: "Question 2?",
+					acceptedAnswer: {
+						"@type": "Answer",
+						text: "Answer 2.",
+					},
+				},
+			],
+		});
+	});
+
+	it("supports FAQ at any heading level", () => {
+		const markdown = `
+# Page
+
+### FAQ
+
+#### What is NEXT?
+
+A platform for customer intelligence.
+`;
+
+		const json = markdownFaqToJsonLd(markdown);
+
+		expect(json.mainEntity).toHaveLength(1);
+		expect(json.mainEntity[0].name).toBe("What is NEXT?");
+	});
+
+	it("stops parsing at the next sibling section", () => {
+		const markdown = `
+## FAQ
+
+### Question 1?
+
+Answer 1.
+
+## Pricing
+
+### Should not be included
+
+Answer 2.
+`;
+
+		const json = markdownFaqToJsonLd(markdown);
+
+		expect(json.mainEntity).toHaveLength(1);
+		expect(json.mainEntity[0].name).toBe("Question 1?");
+	});
+
+	it("normalizes markdown inside answers", () => {
+		const markdown = `
+## FAQ
+
+### What is it?
+
+This is **bold**, *italic*, and a [link](https://example.com).
+`;
+
+		const json = markdownFaqToJsonLd(markdown);
+
+		expect(json.mainEntity[0].acceptedAnswer.text).toBe(
+			"This is bold, italic, and a link.",
+		);
+	});
+});

package/src/markdown-to-framer/cli.ts

@@ -0,0 +1,6 @@
+import { runCli } from "./index";
+
+await runCli().catch((error) => {
+	console.error(error instanceof Error ? error.message : error);
+	process.exitCode = 1;
+});