framer-cms-markdown 0.0.1

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

@@ -0,0 +1,251 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import type { CollectionItemInput, Field } from "framer-api";
+
+import { slugify } from "../libs/framer/filename";
+import {
+	createFieldDataEntryInput,
+	type FramerCollectionItemExport,
+} from "../libs/framer/framer-client";
+import { parseFrontmatterDocument } from "../libs/framer/frontmatter";
+import {
+	markdownToHtml,
+	splitMarkdownIntoSections,
+} from "../libs/framer/markdown";
+
+import { markdownFaqToJsonLd } from "./json-ld-faq";
+
+const SECTION_HTML_FIELD_PATTERN = /^Section\s+(\d+)\s+HTML$/i;
+const SECTION_TITLE_FIELD_PATTERN = /^Section\s+(\d+)\s+Title$/i;
+
+export type MarkdownDocument = {
+	path: string;
+	slug: string;
+	metadata: Record<string, unknown>;
+	body: string;
+};
+
+type SectionField = Field & { type: "formattedText" };
+type SectionTitleField = Field;
+
+export async function listMarkdownFiles(rootDir: string): Promise<string[]> {
+	const entries = await fs.readdir(rootDir, { withFileTypes: true });
+	const files = await Promise.all(
+		entries.map(async (entry) => {
+			const entryPath = path.join(rootDir, entry.name);
+
+			if (entry.isDirectory()) {
+				return listMarkdownFiles(entryPath);
+			}
+
+			return entry.isFile() && entry.name.endsWith(".md") ? [entryPath] : [];
+		}),
+	);
+
+	return files.flat().sort((left, right) => left.localeCompare(right));
+}
+
+export async function readMarkdownDocuments(
+	contentDir: string,
+): Promise<MarkdownDocument[]> {
+	const files = await listMarkdownFiles(contentDir);
+
+	return Promise.all(
+		files.map(async (filePath) => {
+			const raw = await fs.readFile(filePath, "utf8");
+			const { data, body } = parseFrontmatterDocument(raw);
+			const slug =
+				typeof data.slug === "string" && data.slug.trim().length > 0
+					? data.slug
+					: slugify(path.basename(filePath, ".md"));
+
+			return {
+				path: filePath,
+				slug,
+				metadata: data,
+				body,
+			};
+		}),
+	);
+}
+
+export function resolveSectionHtmlFields(fields: Field[]): SectionField[] {
+	return fields
+		.filter((field): field is SectionField => {
+			return (
+				field.type === "formattedText" &&
+				SECTION_HTML_FIELD_PATTERN.test(field.name)
+			);
+		})
+		.sort((left, right) => {
+			const leftOrder = Number.parseInt(
+				left.name.match(SECTION_HTML_FIELD_PATTERN)?.[1] ?? "0",
+				10,
+			);
+			const rightOrder = Number.parseInt(
+				right.name.match(SECTION_HTML_FIELD_PATTERN)?.[1] ?? "0",
+				10,
+			);
+
+			return leftOrder - rightOrder || left.name.localeCompare(right.name);
+		});
+}
+
+export function resolveSectionTitleFields(
+	fields: Field[],
+): SectionTitleField[] {
+	return fields
+		.filter((field) => SECTION_TITLE_FIELD_PATTERN.test(field.name))
+		.sort((left, right) => {
+			const leftOrder = Number.parseInt(
+				left.name.match(SECTION_TITLE_FIELD_PATTERN)?.[1] ?? "0",
+				10,
+			);
+			const rightOrder = Number.parseInt(
+				right.name.match(SECTION_TITLE_FIELD_PATTERN)?.[1] ?? "0",
+				10,
+			);
+
+			return leftOrder - rightOrder || left.name.localeCompare(right.name);
+		});
+}
+
+export function extractSectionTitle(markdown: string): string {
+	const match = markdown.match(/^#{1,6}\s+(.+?)\s*$/m);
+	if (!match) {
+		return "";
+	}
+
+	return match[1].replace(/\s+#+\s*$/, "").trim();
+}
+
+export async function buildFieldDataInput(
+	document: MarkdownDocument,
+	fields: Field[],
+	config: {
+		markdown: string;
+		metadata: string[];
+	},
+): Promise<CollectionItemInput["fieldData"]> {
+	const fieldByName = new Map(fields.map((field) => [field.name, field]));
+	const fieldData: NonNullable<CollectionItemInput["fieldData"]> = {};
+
+	const jsonLd = markdownFaqToJsonLd(document.body);
+	if (jsonLd) {
+		const field = fieldByName.get("JSON-LD");
+		fieldData[field.id] = {
+			type: "string",
+			value: JSON.stringify(jsonLd),
+		};
+	}
+
+	for (const metadataFieldName of config.metadata) {
+		const field = fieldByName.get(metadataFieldName);
+		if (!field) {
+			throw new Error(
+				`Field "${metadataFieldName}" from config was not found in Framer collection.`,
+			);
+		}
+
+		const value = document.metadata[metadataFieldName];
+		if (value === undefined) {
+			continue;
+		}
+
+		const input = createFieldDataEntryInput(field, value, {
+			formattedTextContentType: "markdown",
+		});
+		if (!input) {
+			throw new Error(
+				`Field "${metadataFieldName}" could not be populated from frontmatter value ${JSON.stringify(value)}.`,
+			);
+		}
+
+		fieldData[field.id] = input;
+	}
+
+	if (config.markdown === "sections") {
+		const sectionFields = resolveSectionHtmlFields(fields);
+		const titleFields = resolveSectionTitleFields(fields);
+		const sections = splitMarkdownIntoSections(document.body);
+
+		if (sections.length > sectionFields.length) {
+			throw new Error(
+				`Document "${document.path}" has ${sections.length} sections, but Framer collection only exposes ${sectionFields.length} "Section NN HTML" fields.`,
+			);
+		}
+
+		for (const field of sectionFields) {
+			fieldData[field.id] = {
+				type: field.type,
+				value: "",
+				contentType: "html",
+			};
+		}
+
+		for (const field of titleFields) {
+			const input = createFieldDataEntryInput(field, "");
+			if (input) {
+				fieldData[field.id] = input;
+			}
+		}
+
+		for (const [index, section] of sections.entries()) {
+			const field = sectionFields[index];
+			const titleField = titleFields[index];
+			const html = await markdownToHtml(section);
+			const title = extractSectionTitle(section);
+			fieldData[field.id] = {
+				type: field.type,
+				value: html,
+				contentType: "html",
+			};
+			if (titleField) {
+				const input = createFieldDataEntryInput(titleField, title);
+				if (input) {
+					fieldData[titleField.id] = input;
+				}
+			}
+		}
+
+		return fieldData;
+	}
+
+	const markdownField = fieldByName.get(config.markdown);
+	if (!markdownField) {
+		throw new Error(
+			`Markdown field "${config.markdown}" from config was not found in Framer collection.`,
+		);
+	}
+
+	const bodyInput = createFieldDataEntryInput(markdownField, document.body, {
+		formattedTextContentType: "markdown",
+	});
+	if (!bodyInput) {
+		throw new Error(
+			`Markdown field "${config.markdown}" could not accept the document body.`,
+		);
+	}
+	fieldData[markdownField.id] = bodyInput;
+
+	return fieldData;
+}
+
+export async function buildCollectionItemInput(
+	document: MarkdownDocument,
+	fields: Field[],
+	config: {
+		markdown: string;
+		metadata: string[];
+	},
+	existingItemsBySlug: Map<string, FramerCollectionItemExport>,
+): Promise<CollectionItemInput> {
+	const existing = existingItemsBySlug.get(document.slug);
+
+	return {
+		id: existing?.id,
+		slug: document.slug,
+		fieldData: await buildFieldDataInput(document, fields, config),
+	};
+}

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

@@ -0,0 +1,83 @@
+import path from "node:path";
+import process from "node:process";
+
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+
+import { loadConfig } from "../libs/framer/config";
+import {
+	FramerClient,
+	type FramerCollectionItemExport,
+} from "../libs/framer/framer-client";
+
+import { buildCollectionItemInput, readMarkdownDocuments } from "./import";
+
+export type CliArgs = {
+	token?: string;
+	config: string;
+};
+
+export async function runCli(argv = hideBin(process.argv)): Promise<void> {
+	const args = await yargs(argv)
+		.scriptName("markdown-to-framer")
+		.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 sync 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 contentDir = path.resolve(
+		config.content ?? path.join("content", config.collection),
+	);
+	const documents = await readMarkdownDocuments(contentDir);
+	const client = new FramerClient({
+		projectRef: config.site,
+		token,
+	});
+
+	try {
+		const { collection, fields, items } = await client.getCollectionExportData(
+			config.collection,
+		);
+		const existingItemsBySlug = new Map(
+			items.map((item: FramerCollectionItemExport) => [item.slug, item]),
+		);
+		const upserts = [];
+
+		for (const document of documents) {
+			upserts.push(
+				await buildCollectionItemInput(
+					document,
+					fields,
+					config,
+					existingItemsBySlug,
+				),
+			);
+		}
+
+		await client.upsertCollectionItems(collection, upserts);
+
+		for (const document of documents) {
+			console.log(document.slug);
+		}
+	} finally {
+		await client.disconnect();
+	}
+}

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

@@ -0,0 +1,146 @@
+type FaqItem = {
+	question: string;
+	answer: string;
+};
+
+export interface JsonLd {
+	"@context": string;
+	"@type": string;
+	mainEntity: {
+		"@type": string;
+		name: string;
+		acceptedAnswer: {
+			"@type": string;
+			text: string;
+		};
+	}[];
+}
+
+function parseHeading(line: string): { level: number; text: string } | null {
+	const match = /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(line);
+
+	if (!match) {
+		return null;
+	}
+
+	return {
+		level: match[1].length,
+		text: match[2].trim(),
+	};
+}
+
+function normalizeMarkdownText(markdown: string): string {
+	return markdown
+		.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+		.replace(/[*_`>#-]/g, "")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+function findFaqHeading(
+	lines: string[],
+): { index: number; level: number } | null {
+	for (let i = 0; i < lines.length; i++) {
+		const heading = parseHeading(lines[i]);
+
+		if (heading && heading.text.trim().toLowerCase() === "faq") {
+			return { index: i, level: heading.level };
+		}
+	}
+
+	return null;
+}
+
+function collectSection(
+	lines: string[],
+	startIndex: number,
+	parentLevel: number,
+): string[] {
+	const section: string[] = [];
+
+	for (let i = startIndex; i < lines.length; i++) {
+		const heading = parseHeading(lines[i]);
+
+		if (heading && heading.level <= parentLevel) {
+			break;
+		}
+
+		section.push(lines[i]);
+	}
+
+	return section;
+}
+
+function extractQuestions(lines: string[], faqLevel: number): FaqItem[] {
+	const items: FaqItem[] = [];
+
+	let currentQuestion: string | null = null;
+	let currentAnswerLines: string[] = [];
+
+	const flush = () => {
+		if (!currentQuestion) {
+			return;
+		}
+
+		const answer = normalizeMarkdownText(currentAnswerLines.join("\n"));
+
+		if (answer.length > 0) {
+			items.push({
+				question: currentQuestion,
+				answer,
+			});
+		}
+	};
+
+	for (const line of lines) {
+		const heading = parseHeading(line);
+
+		if (heading && heading.level > faqLevel) {
+			flush();
+			currentQuestion = heading.text;
+			currentAnswerLines = [];
+		} else if (currentQuestion) {
+			currentAnswerLines.push(line);
+		}
+	}
+
+	flush();
+
+	return items;
+}
+
+function extractFaqItems(markdown: string): FaqItem[] {
+	const lines = markdown.split(/\r?\n/);
+
+	const faqStart = findFaqHeading(lines);
+	if (!faqStart) {
+		return [];
+	}
+
+	const { index: faqIndex, level: faqLevel } = faqStart;
+	const faqLines = collectSection(lines, faqIndex + 1, faqLevel);
+
+	return extractQuestions(faqLines, faqLevel);
+}
+
+export function markdownFaqToJsonLd(markdown: string): JsonLd | null {
+	const items = extractFaqItems(markdown);
+	if (items.length === 0) {
+		return null;
+	}
+
+	const jsonLd: JsonLd = {
+		"@context": "https://schema.org",
+		"@type": "FAQPage",
+		mainEntity: items.map((item) => ({
+			"@type": "Question",
+			name: item.question,
+			acceptedAnswer: {
+				"@type": "Answer",
+				text: item.answer,
+			},
+		})),
+	};
+
+	return jsonLd;
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+	"compilerOptions": {
+		"target": "ES2020",
+		"module": "ESNext",
+		"moduleResolution": "Bundler",
+		"outDir": "dist",
+		"rootDir": ".",
+		"lib": ["DOM", "ES2020"],
+		"jsx": "preserve",
+		"allowJs": true,
+		"resolveJsonModule": true,
+		"esModuleInterop": true,
+		"allowSyntheticDefaultImports": true,
+		"types": ["node", "jest"],
+		"skipLibCheck": true,
+		"ignoreDeprecations": "6.0",
+		"strict": false
+	},
+	"include": ["src/**/*", "test/**/*"]
+}