folderblog

Official SDK for folder.blog — API client, server middleware, markdown processor, and CLI in one package.

Install

npm i folderblog

API Client

Read posts from any folder.blog site:

import { folderBlog } from "folderblog";

const blog = folderBlog("yourname.folder.blog");

const posts = await blog.posts.list();
const post = await blog.posts.get("hello-world");
const site = await blog.site.get();
const tags = await blog.tags.list();
const rss = await blog.feed.rss();

Markdown Processor

Process a folder of markdown files into structured JSON:

import { processFolder } from "folderblog";

const result = await processFolder({
  dir: { input: "./content", output: "./dist" },
});

console.log(`${result.posts.length} posts processed`);

Enable wiki-link resolution (Obsidian-style [[links]]):

const result = await processFolder({
  dir: { input: "./vault", output: "./dist" },
  pipeline: { wikiLinks: true },
});

Using the Processor class directly

import { Processor } from "folderblog";

const processor = new Processor({
  config: {
    dir: { input: "./content", output: "./dist" },
    pipeline: { gfm: true, allowRawHtml: true },
  },
});

await processor.initialize();
const result = await processor.process();
await processor.dispose();

Markdown utilities

import { processMarkdown, parseFrontmatter, toSlug } from "folderblog";

const { html, frontmatter } = await processMarkdown("# Hello\n\nWorld");
const slug = toSlug("My Blog Post"); // 'my-blog-post'

Server Middleware

Proxy a folder.blog into your app. Works with any Web Standard Request/Response framework:

import { createHandler } from "folderblog/server";

const handler = createHandler({
  domain: "yourname.folder.blog",
  basePath: "/blog",
});

// Hono
app.get("/blog/*", (c) => handler(c.req.raw));

// Node.js / any Web Standard server
const response = await handler(request);

CLI

npx folderblog build                    # Auto-detect config
npx folderblog build -i ./content       # Specify input dir
npx folderblog build -o ./dist          # Specify output dir
npx folderblog build -c my.config.js    # Custom config file

Config file (auto-detected as folderblog.config.{js,mjs,ts}):

export default {
  dir: { input: "./content", output: "./dist" },
  pipeline: { gfm: true, wikiLinks: true },
};

Sub-path Imports

For tree-shaking, import from specific sub-paths:

import { Processor } from "folderblog/processor";
import { PluginManager } from "folderblog/processor/plugins";
import type { ProcessConfig, ProcessedPost } from "folderblog/processor/types";
import { createHandler } from "folderblog/server";
import { build } from "folderblog/cli";

Everything is also available from the main 'folderblog' entry point.

Error Handling

import { folderBlog, NotFoundError, ApiError, NetworkError } from "folderblog";

const blog = folderBlog("yourname.folder.blog");

try {
  const post = await blog.posts.get("missing");
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log("Post not found");
  } else if (err instanceof ApiError) {
    console.log(`API error: ${err.status}`);
  } else if (err instanceof NetworkError) {
    console.log("Network failure", err.cause);
  }
}

License

MIT