framer-cms-markdown 0.0.1

package/dist/src/framer-sync/filename.js

@@ -0,0 +1,41 @@
+export function slugify(input) {
+    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, existingNames) {
+    if (!existingNames.has(baseName)) {
+        return baseName;
+    }
+    let suffix = 2;
+    while (existingNames.has(`${baseName}-${suffix}`)) {
+        suffix += 1;
+    }
+    return `${baseName}-${suffix}`;
+}
+export function resolveMarkdownFilename(item, existingNames = new Set()) {
+    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/dist/src/framer-sync/format.js

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

package/dist/src/framer-sync/framer-client.js

@@ -0,0 +1,180 @@
+import { connect, } from "framer-api";
+function extractAssetUrl(value) {
+    if (!value || typeof value !== "object") {
+        return undefined;
+    }
+    const record = value;
+    return typeof record.url === "string" ? record.url : undefined;
+}
+function extractIdOrString(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (!value || typeof value !== "object") {
+        return undefined;
+    }
+    const record = value;
+    if (typeof record.id === "string") {
+        return record.id;
+    }
+    if (typeof record.name === "string") {
+        return record.name;
+    }
+    return undefined;
+}
+function normalizeFieldEntry(entry) {
+    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, value, options = {}) {
+    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 }
+                : undefined;
+        case "collectionReference":
+            return typeof value === "string" || value === null
+                ? { type: field.type, value: value }
+                : undefined;
+        case "multiCollectionReference":
+            return Array.isArray(value) &&
+                value.every((entry) => typeof entry === "string")
+                ? { type: field.type, value: value }
+                : undefined;
+        case "color":
+        case "file":
+        case "image":
+            return typeof value === "string" || value === null
+                ? { type: field.type, value: value }
+                : undefined;
+        case "array":
+        case "divider":
+        case "unsupported":
+            return undefined;
+        default:
+            return undefined;
+    }
+}
+export class FramerClient {
+    constructor(options) {
+        this.projectRef = options.projectRef;
+        this.token = options.token;
+    }
+    async connect() {
+        if (!this.framer) {
+            this.framer = await connect(this.projectRef, this.token);
+        }
+    }
+    async disconnect() {
+        if (this.framer) {
+            await this.framer.disconnect();
+            this.framer = undefined;
+        }
+    }
+    async getCollections() {
+        return (await this.getFramer()).getCollections();
+    }
+    async resolveCollection(collectionRef) {
+        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) {
+        const collection = await this.resolveCollection(collectionRef);
+        const fields = await collection.getFields();
+        const items = await collection.getItems();
+        return { collection, fields, items };
+    }
+    async getCollectionExportData(collectionRef) {
+        const { collection, fields, items } = await this.getCollectionData(collectionRef);
+        return {
+            collection,
+            fields,
+            items: items.map((item) => this.toExportItem(item, fields)),
+        };
+    }
+    async upsertCollectionItems(collection, items) {
+        await collection.addItems(items);
+    }
+    async getFramer() {
+        await this.connect();
+        if (!this.framer) {
+            throw new Error("Failed to connect to Framer");
+        }
+        return this.framer;
+    }
+    toExportItem(item, fields) {
+        const fieldData = {};
+        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/dist/src/framer-sync/frontmatter.js

@@ -0,0 +1,49 @@
+import yaml from "yaml";
+function normalizeYamlValue(value) {
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (Array.isArray(value)) {
+        return value.map(normalizeYamlValue);
+    }
+    if (value && typeof value === "object") {
+        const output = {};
+        for (const [key, nestedValue] of Object.entries(value)) {
+            if (nestedValue !== undefined) {
+                output[key] = normalizeYamlValue(nestedValue);
+            }
+        }
+        return output;
+    }
+    return value;
+}
+export function toFrontmatter(data) {
+    const filtered = {};
+    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) {
+    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);
+    const data = parsed && typeof parsed === "object" && !Array.isArray(parsed)
+        ? parsed
+        : {};
+    return {
+        data,
+        body: rawBody.replace(/^\n+/, ""),
+    };
+}

package/dist/src/framer-sync/markdown.js

@@ -0,0 +1,70 @@
+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) {
+    return markdown.trim().replace(/\n{3,}/g, "\n\n");
+}
+function stripMarkdownComments(markdown) {
+    return markdown.replace(/<!--[\s\S]*?-->\s*/g, "").trim();
+}
+export async function htmlToMarkdown(html) {
+    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) {
+    const input = stripMarkdownComments(markdown);
+    if (!input) {
+        return "";
+    }
+    const file = await markdownToHtmlProcessor.process(input);
+    return String(file).trim();
+}
+export function splitMarkdownIntoSections(markdown) {
+    const normalized = markdown.replace(/\r\n/g, "\n").trim();
+    if (!normalized) {
+        return [];
+    }
+    const lines = normalized.split("\n");
+    const sections = [];
+    let current = [];
+    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/dist/src/framer-to-markdown/__tests__/export.spec.js

@@ -0,0 +1,64 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "@jest/globals";
+import { exportItemsToMarkdown } from "../export";
+const tempDirs = [];
+afterEach(async () => {
+    await Promise.all(tempDirs
+        .splice(0)
+        .map((dir) => fs.rm(dir, { recursive: true, force: true })));
+});
+describe("export", () => {
+    it("writes the configured markdown body and curated frontmatter", async () => {
+        const outputDir = await fs.mkdtemp(path.join(os.tmpdir(), "framer-cms-markdown-"));
+        tempDirs.push(outputDir);
+        const [writtenFile] = await exportItemsToMarkdown([
+            {
+                id: "1",
+                slug: "example-post",
+                draft: false,
+                fieldData: {
+                    Title: "Example Post",
+                    Excerpt: "Short summary",
+                    "Section 02 HTML": '<h2 dir="auto">Second</h2><p dir="auto">Hello world.</p>',
+                    "Section 01 HTML": '<!-- internal metadata --><h1 dir="auto">Example Post</h1><p dir="auto">Intro text.</p>',
+                    "Workflow Archetype": "continuous_enrichment",
+                    "Primary Team": "Product",
+                    "Company Type": "SaaS",
+                    "Strategic Category": "Product Intelligence",
+                    "Business Outcome": "Improve roadmap prioritization",
+                },
+            },
+        ], {
+            outputDir,
+            bodyFieldName: "sections",
+            frontmatterFields: [
+                "Title",
+                "Excerpt",
+                "Workflow Archetype",
+                "Primary Team",
+                "Company Type",
+                "Strategic Category",
+                "Business Outcome",
+            ],
+        });
+        const contents = await fs.readFile(writtenFile, "utf8");
+        expect(contents).toContain("slug: example-post");
+        expect(contents).toContain("Title: Example Post");
+        expect(contents).toContain("Excerpt: Short summary");
+        expect(contents).toContain("Workflow Archetype: continuous_enrichment");
+        expect(contents).toContain("Primary Team: Product");
+        expect(contents).toContain("Company Type: SaaS");
+        expect(contents).toContain("Strategic Category: Product Intelligence");
+        expect(contents).toContain("Business Outcome: Improve roadmap prioritization");
+        expect(contents).not.toContain("draft:");
+        expect(contents).not.toContain("internal metadata");
+        expect(contents).toContain("# Example Post");
+        expect(contents).toContain("Intro text.");
+        expect(contents).toContain("## Second");
+        expect(contents).toContain("Hello world.");
+        expect(contents.indexOf("# Example Post")).toBeLessThan(contents.indexOf("## Second"));
+        expect(contents.endsWith("\n")).toBe(true);
+    });
+});

package/dist/src/framer-to-markdown/__tests__/faq.spec.js

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "@jest/globals";
+import { containsFaqHeading, parseFaqEntries, renderFaqMarkdown, } from "../faq";
+describe("faq", () => {
+    it("parses faq json entries", () => {
+        const entries = parseFaqEntries(JSON.stringify([
+            { question: "What is this?", answer: "An FAQ." },
+            { question: "", answer: "ignored" },
+        ]));
+        expect(entries).toEqual([{ question: "What is this?", answer: "An FAQ." }]);
+    });
+    it("renders faq markdown", () => {
+        const markdown = renderFaqMarkdown([
+            { question: "What is this?", answer: "An FAQ." },
+        ]);
+        expect(markdown).toContain("## FAQ");
+        expect(markdown).toContain("### What is this?");
+        expect(markdown).toContain("An FAQ.");
+    });
+    it("detects existing faq headings", () => {
+        expect(containsFaqHeading("## FAQ\n\nHello\n")).toBe(true);
+        expect(containsFaqHeading("# Not FAQ\n")).toBe(false);
+    });
+});

package/dist/src/framer-to-markdown/__tests__/filename.spec.js

@@ -0,0 +1,15 @@
+import { describe, expect, it } from "@jest/globals";
+import { resolveMarkdownFilename, slugify, uniqueName } from "../filename";
+describe("filename", () => {
+    it("slugify normalizes text", () => {
+        expect(slugify("Hello, Framer CMS!")).toBe("hello-framer-cms");
+    });
+    it("uniqueName adds suffixes", () => {
+        const existing = new Set(["post", "post-2"]);
+        expect(uniqueName("post", existing)).toBe("post-3");
+    });
+    it("resolveMarkdownFilename prefers slug", () => {
+        const existing = new Set();
+        expect(resolveMarkdownFilename({ slug: "hello-world" }, existing)).toBe("hello-world.md");
+    });
+});

package/dist/src/framer-to-markdown/__tests__/framer-ref.spec.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const globals_1 = require("@jest/globals");
+const framer_ref_1 = require("../framer-ref");
+(0, globals_1.describe)("framer ref", () => {
+    (0, globals_1.it)("extracts the project id from a framer project url", () => {
+        (0, globals_1.expect)((0, framer_ref_1.normalizeFramerProjectRef)("https://framer.com/projects/NEXT-Production-v2--JCo5wuC0juGVNOJSk41P-dcViX")).toBe("JCo5wuC0juGVNOJSk41P-dcViX");
+    });
+    (0, globals_1.it)("keeps a bare project id unchanged", () => {
+        (0, globals_1.expect)((0, framer_ref_1.normalizeFramerProjectRef)("JCo5wuC0juGVNOJSk41P-dcViX")).toBe("JCo5wuC0juGVNOJSk41P-dcViX");
+    });
+});

package/dist/src/framer-to-markdown/__tests__/frontmatter.spec.js

@@ -0,0 +1,15 @@
+import { describe, expect, it } from "@jest/globals";
+import { toFrontmatter } from "../frontmatter";
+describe("frontmatter", () => {
+    it("serializes yaml frontmatter", () => {
+        const output = toFrontmatter({
+            title: "Hello",
+            tags: ["a", "b"],
+            published: true,
+        });
+        expect(output).toMatch(/^---\n/);
+        expect(output).toMatch(/title: Hello/);
+        expect(output).toMatch(/tags:/);
+        expect(output).toMatch(/published: true/);
+    });
+});

package/dist/src/framer-to-markdown/__tests__/markdown.spec.js

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "@jest/globals";
+import { htmlToMarkdown } from "../markdown";
+describe("markdown", () => {
+    it("converts simple html", async () => {
+        const output = await htmlToMarkdown("<h1>Hello</h1><p>World</p>");
+        expect(output).toMatch(/^# Hello/);
+        expect(output).toMatch(/World/);
+    });
+    it("converts html tables to markdown tables", async () => {
+        const output = await htmlToMarkdown([
+            "<figure><table><tbody>",
+            "<tr><th><p>Approach</p></th><th><p>Effect</p></th></tr>",
+            "<tr><td><p>Fix early</p></td><td><p>Cheaper remediation</p></td></tr>",
+            "</tbody></table></figure>",
+        ].join(""));
+        expect(output).toMatch(/\|\s*Approach\s*\|\s*Effect\s*\|/);
+        expect(output).toMatch(/\|\s*-+\s*\|\s*-+\s*\|/);
+        expect(output).toMatch(/\|\s*Fix early\s*\|\s*Cheaper remediation\s*\|/);
+    });
+});

package/dist/src/framer-to-markdown/cli.js

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

package/dist/src/framer-to-markdown/config.js

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

package/dist/src/framer-to-markdown/export.js

@@ -0,0 +1,138 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveMarkdownFilename, slugify } from "./filename";
+import { formatMarkdownDocument } from "./format";
+import { toFrontmatter } from "./frontmatter";
+import { htmlToMarkdown } from "./markdown";
+const SECTION_HTML_FIELD_PATTERN = /^Section\s+(\d+)\s+HTML$/i;
+const BODY_FIELD_CANDIDATES = [
+    "content",
+    "body",
+    "html",
+    "richText",
+    "rich_text",
+];
+function stringValue(value) {
+    return typeof value === "string" ? value : "";
+}
+function looksLikeHtml(value) {
+    return /<\/?[a-z][\s\S]*>/i.test(value);
+}
+function normalizeFrontmatterValue(value) {
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (Array.isArray(value)) {
+        return value.map(normalizeFrontmatterValue);
+    }
+    if (value && typeof value === "object") {
+        const record = {};
+        for (const [key, nestedValue] of Object.entries(value)) {
+            if (nestedValue !== undefined) {
+                record[key] = normalizeFrontmatterValue(nestedValue);
+            }
+        }
+        return record;
+    }
+    return value;
+}
+export function resolveBodyField(item, bodyFieldName) {
+    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;
+}
+export function resolveSectionFields(item) {
+    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, options) {
+    const frontmatter = {
+        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) {
+    return markdown.replace(/<!--[\s\S]*?-->\s*/g, "").trim();
+}
+async function renderBodyContent(value) {
+    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, bodyFieldName) {
+    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, options = {}) {
+    const outputDir = options.outputDir ??
+        path.join(process.cwd(), "export", slugify(options.collectionName ?? "collection"));
+    await fs.mkdir(outputDir, { recursive: true });
+    const usedNames = new Set();
+    const writtenFiles = [];
+    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;
+}