framer-cms-markdown 0.0.1

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

@@ -0,0 +1,221 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { resolveMarkdownFilename, slugify } from "./filename";
+import { formatMarkdownDocument } from "./format";
+import type { FramerCollectionItemExport } from "./framer-client";
+import { toFrontmatter } from "./frontmatter";
+import { htmlToMarkdown } from "./markdown";
+
+export type ExportOptions = {
+	outputDir?: string;
+	collectionName?: string;
+	bodyFieldName?: string;
+	frontmatterFields?: string[];
+};
+
+const SECTION_HTML_FIELD_PATTERN = /^Section\s+(\d+)\s+HTML$/i;
+const BODY_FIELD_CANDIDATES = [
+	"content",
+	"body",
+	"html",
+	"richText",
+	"rich_text",
+];
+
+function stringValue(value: unknown): string {
+	return typeof value === "string" ? value : "";
+}
+
+function looksLikeHtml(value: string): boolean {
+	return /<\/?[a-z][\s\S]*>/i.test(value);
+}
+
+function normalizeFrontmatterValue(value: unknown): unknown {
+	if (value instanceof Date) {
+		return value.toISOString();
+	}
+
+	if (Array.isArray(value)) {
+		return value.map(normalizeFrontmatterValue);
+	}
+
+	if (value && typeof value === "object") {
+		const record: Record<string, unknown> = {};
+		for (const [key, nestedValue] of Object.entries(
+			value as Record<string, unknown>,
+		)) {
+			if (nestedValue !== undefined) {
+				record[key] = normalizeFrontmatterValue(nestedValue);
+			}
+		}
+		return record;
+	}
+
+	return value;
+}
+
+export function resolveBodyField(
+	item: FramerCollectionItemExport,
+	bodyFieldName?: string,
+): string | undefined {
+	if (bodyFieldName === "sections") {
+		return undefined;
+	}
+
+	if (bodyFieldName && item.fieldData[bodyFieldName] !== undefined) {
+		return bodyFieldName;
+	}
+
+	for (const candidate of BODY_FIELD_CANDIDATES) {
+		const value = item.fieldData[candidate];
+		if (typeof value === "string" && stringValue(value).trim().length > 0) {
+			return candidate;
+		}
+	}
+
+	for (const [key, value] of Object.entries(item.fieldData)) {
+		if (typeof value === "string" && looksLikeHtml(value)) {
+			return key;
+		}
+	}
+
+	return undefined;
+}
+
+type SectionField = {
+	name: string;
+	order: number;
+	value: string;
+};
+
+export function resolveSectionFields(
+	item: FramerCollectionItemExport,
+): SectionField[] {
+	return Object.entries(item.fieldData)
+		.flatMap(([key, value]) => {
+			if (typeof value !== "string") {
+				return [];
+			}
+
+			const match = key.match(SECTION_HTML_FIELD_PATTERN);
+			if (!match) {
+				return [];
+			}
+
+			return [
+				{
+					name: key,
+					order: Number.parseInt(match[1], 10),
+					value,
+				},
+			];
+		})
+		.sort(
+			(left, right) =>
+				left.order - right.order || left.name.localeCompare(right.name),
+		);
+}
+
+export function buildFrontmatter(
+	item: FramerCollectionItemExport,
+	options: {
+		frontmatterFields?: string[];
+	},
+): Record<string, unknown> {
+	const frontmatter: Record<string, unknown> = {
+		slug: item.slug,
+	};
+
+	const { frontmatterFields } = options;
+
+	for (const fieldName of frontmatterFields ?? []) {
+		const value = item.fieldData[fieldName];
+		if (
+			value === undefined ||
+			typeof value === "function" ||
+			typeof value === "symbol"
+		) {
+			continue;
+		}
+
+		frontmatter[fieldName] = normalizeFrontmatterValue(value);
+	}
+
+	return frontmatter;
+}
+
+function stripMarkdownComments(markdown: string): string {
+	return markdown.replace(/<!--[\s\S]*?-->\s*/g, "").trim();
+}
+
+async function renderBodyContent(value: unknown): Promise<string> {
+	const text = stringValue(value).trim();
+	if (!text) {
+		return "";
+	}
+
+	const markdown = looksLikeHtml(text) ? await htmlToMarkdown(text) : text;
+	const normalized = stripMarkdownComments(markdown);
+	return normalized.length > 0 ? `${normalized}\n` : "";
+}
+
+export function renderMarkdownBody(
+	item: FramerCollectionItemExport,
+	bodyFieldName?: string,
+): Promise<string> {
+	const sectionFields = resolveSectionFields(item);
+	if (bodyFieldName === "sections" || sectionFields.length > 0) {
+		return Promise.all(
+			sectionFields.map((section) => renderBodyContent(section.value)),
+		).then((sections) =>
+			sections
+				.map((section) => section.trim())
+				.filter((section) => section.length > 0)
+				.join("\n\n")
+				.trim()
+				.concat(sectionFields.length > 0 ? "\n" : ""),
+		);
+	}
+
+	const bodyField = resolveBodyField(item, bodyFieldName);
+	return bodyField
+		? renderBodyContent(item.fieldData[bodyField])
+		: Promise.resolve("");
+}
+
+export async function exportItemsToMarkdown(
+	items: FramerCollectionItemExport[],
+	options: ExportOptions = {},
+): Promise<string[]> {
+	const outputDir =
+		options.outputDir ??
+		path.join(
+			process.cwd(),
+			"export",
+			slugify(options.collectionName ?? "collection"),
+		);
+
+	await fs.mkdir(outputDir, { recursive: true });
+
+	const usedNames = new Set<string>();
+	const writtenFiles: string[] = [];
+
+	for (const item of items) {
+		const filename = resolveMarkdownFilename(item, usedNames);
+		const filepath = path.join(outputDir, filename);
+		const frontmatter = buildFrontmatter(item, {
+			frontmatterFields: options.frontmatterFields,
+		});
+		const markdownBody = await renderMarkdownBody(item, options.bodyFieldName);
+
+		const fileContents = await formatMarkdownDocument(
+			`${toFrontmatter(frontmatter)}${markdownBody}`,
+		);
+
+		await fs.writeFile(filepath, fileContents, "utf8");
+		writtenFiles.push(filepath);
+	}
+
+	return writtenFiles;
+}

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

@@ -0,0 +1,5 @@
+export {
+	resolveMarkdownFilename,
+	slugify,
+	uniqueName,
+} from "../libs/framer/filename";

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

@@ -0,0 +1 @@
+export { formatMarkdownDocument } from "../libs/framer/format";

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

@@ -0,0 +1,6 @@
+export {
+	createFieldDataEntryInput,
+	FramerClient,
+	type FramerClientOptions,
+	type FramerCollectionItemExport,
+} from "../libs/framer/framer-client";

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

@@ -0,0 +1,4 @@
+export {
+	parseFrontmatterDocument,
+	toFrontmatter,
+} from "../libs/framer/frontmatter";

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

@@ -0,0 +1,63 @@
+import path from "node:path";
+import process from "node:process";
+
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+
+import { loadConfig } from "./config";
+import { exportItemsToMarkdown } from "./export";
+import { FramerClient } from "./framer-client";
+
+export type CliArgs = {
+	token?: string;
+	config: string;
+};
+
+export async function runCli(argv = hideBin(process.argv)): Promise<void> {
+	const args = await yargs(argv)
+		.scriptName("framer-to-markdown")
+		.usage("$0 --token <token> --config config/use-cases.yml")
+		.option("token", {
+			type: "string",
+			describe: "Framer API token. Falls back to FRAMER_TOKEN.",
+		})
+		.option("config", {
+			type: "string",
+			demandOption: true,
+			describe: "Path to a single export config file",
+		})
+		.strict()
+		.help()
+		.parse();
+
+	const cliArgs = args as unknown as CliArgs;
+	const token = cliArgs.token ?? process.env.FRAMER_TOKEN;
+	if (!token) {
+		throw new Error(
+			"Framer token is required. Pass --token or set FRAMER_TOKEN.",
+		);
+	}
+
+	const { config } = await loadConfig(cliArgs.config);
+
+	const client = new FramerClient({
+		projectRef: config.site,
+		token,
+	});
+
+	try {
+		const data = await client.getCollectionExportData(config.collection);
+		const writtenFiles = await exportItemsToMarkdown(data.items, {
+			outputDir: config.content ? path.resolve(config.content) : undefined,
+			collectionName: data.collection.name ?? data.collection.id,
+			bodyFieldName: config.markdown,
+			frontmatterFields: config.metadata,
+		});
+
+		for (const file of writtenFiles) {
+			console.log(file);
+		}
+	} finally {
+		await client.disconnect();
+	}
+}

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

@@ -0,0 +1,5 @@
+export {
+	htmlToMarkdown,
+	markdownToHtml,
+	splitMarkdownIntoSections,
+} from "../libs/framer/markdown";

package/src/libs/framer/config.ts

@@ -0,0 +1,79 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import yaml from "yaml";
+
+export type SyncConfig = {
+	site: string;
+	collection: string;
+	content?: string;
+	markdown: string;
+	metadata: string[];
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function parseMetadataConfig(value: unknown): string[] {
+	if (!Array.isArray(value)) {
+		throw new Error('Config "metadata" must be an array.');
+	}
+
+	const fields = value.map((entry, index) => {
+		if (typeof entry !== "string" || entry.trim().length === 0) {
+			throw new Error(
+				`Config "metadata[${index}]" must be a non-empty string.`,
+			);
+		}
+
+		return entry;
+	});
+
+	if (fields.length === 0) {
+		throw new Error('Config "metadata" must define at least one field.');
+	}
+
+	return fields;
+}
+
+export async function loadConfig(
+	configPath: string,
+): Promise<{ config: SyncConfig; resolvedPath: string }> {
+	const resolvedPath = path.resolve(configPath);
+	const raw = await fs.readFile(resolvedPath, "utf8");
+	const parsed = yaml.parse(raw) as unknown;
+
+	if (!isRecord(parsed)) {
+		throw new Error("Config file must contain a single object.");
+	}
+
+	if (typeof parsed.site !== "string" || parsed.site.trim().length === 0) {
+		throw new Error('Config "site" must be a non-empty string.');
+	}
+
+	if (
+		typeof parsed.collection !== "string" ||
+		parsed.collection.trim().length === 0
+	) {
+		throw new Error('Config "collection" must be a non-empty string.');
+	}
+
+	if (
+		typeof parsed.markdown !== "string" ||
+		parsed.markdown.trim().length === 0
+	) {
+		throw new Error('Config "markdown" must be a non-empty string.');
+	}
+
+	return {
+		resolvedPath,
+		config: {
+			site: parsed.site,
+			collection: parsed.collection,
+			content: typeof parsed.content === "string" ? parsed.content : undefined,
+			markdown: parsed.markdown,
+			metadata: parseMetadataConfig(parsed.metadata),
+		},
+	};
+}

package/src/libs/framer/filename.ts

@@ -0,0 +1,59 @@
+export function slugify(input: string): string {
+	const normalized = input
+		.normalize("NFKD")
+		.replace(/[\u0300-\u036f]/g, "")
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.replace(/-{2,}/g, "-");
+
+	return normalized.length > 0 ? normalized : "item";
+}
+
+export function uniqueName(
+	baseName: string,
+	existingNames: Set<string>,
+): string {
+	if (!existingNames.has(baseName)) {
+		return baseName;
+	}
+
+	let suffix = 2;
+	while (existingNames.has(`${baseName}-${suffix}`)) {
+		suffix += 1;
+	}
+
+	return `${baseName}-${suffix}`;
+}
+
+export function resolveMarkdownFilename(
+	item: {
+		slug?: string | null;
+		title?: string | null;
+		id?: string | number | null;
+	},
+	existingNames: Set<string> = new Set(),
+): string {
+	const candidates = [
+		item.slug,
+		item.title,
+		item.id != null ? String(item.id) : null,
+	];
+
+	for (const candidate of candidates) {
+		if (!candidate) {
+			continue;
+		}
+
+		const name = slugify(candidate);
+		if (name) {
+			const unique = uniqueName(name, existingNames);
+			existingNames.add(unique);
+			return `${unique}.md`;
+		}
+	}
+
+	const fallback = uniqueName("item", existingNames);
+	existingNames.add(fallback);
+	return `${fallback}.md`;
+}

package/src/libs/framer/format.ts

@@ -0,0 +1,12 @@
+import * as markdownPlugin from "prettier/plugins/markdown";
+import * as prettier from "prettier/standalone";
+
+export async function formatMarkdownDocument(
+	markdown: string,
+): Promise<string> {
+	return prettier.format(markdown, {
+		parser: "markdown",
+		plugins: [markdownPlugin],
+		proseWrap: "preserve",
+	});
+}