Learn Folio

1. Getting Started

Folio is a macOS-first desktop application engineered with Electron, React, CodeMirror 6, and Paged.js. It bridges the gap between lightweight Markdown writing and executive-ready A4 PDF publishing.

Installation

Download the official release for your operating system:

Tip: On macOS, drag Folio.app into /Applications. On Windows, run the installer .exe. On Linux, make the .AppImage executable with chmod +x or install the .deb package.

Editor Interface & Shortcuts

Folio features a synchronized split pane: write on the left with full CodeMirror syntax highlighting, and watch realistic A4 pages format in real-time on the right.

2. Document Front Matter

Folio documents are 100% standard Markdown. You can optionally include a YAML frontmatter block at the very top of your document to configure layouts, metadata, invoices, or running headers and footers.

A. Cover Report / SOW (layout: cover-report)

The default layout for statements of work, proposals, whitepapers, and formal reports. Generates a branded cover page with metadata fields, followed by numbered pages.

---
layout: cover-report
title: Enterprise Cloud Architecture Proposal
kicker: Technical Proposal
client: Acme Global Industries
prepared-for: Marcus Vance, CTO
prepared-by: Meridian Cloud Advisory
date: October 12, 2026
valid-until: November 12, 2026
document-id: SOW-2026-089
theme: editorial
lang: en
---

# Executive Summary

This proposal outlines the multi-region migration strategy...

B. Invoices (layout: invoice)

A dedicated commercial invoice layout. Folio automatically renders clean vendor/client header cards, a formatted line items table, subtotal, tax rate, total due, and remittance instructions.

---
layout: invoice
title: Invoice INV-2026-0042
client: Northstar Technologies
prepared-by: Carlos Rivera Studio
date: 2026-10-15
theme: contrast
invoice:
  number: INV-2026-0042
  issue-date: 2026-10-15
  due-date: 2026-11-15
  currency: USD
  tax-rate: 8.5
  items:
    - description: Brand Identity Design System
      quantity: 1
      unit-price: 4500
      total: 4500
    - description: Design System Component Tokens
      quantity: 40
      unit-price: 75
      total: 3000
  notes: Payment due within 30 days via wire transfer or ACH.
  bank:
    name: Silicon Valley Bank
    account: "4820-9182-01"
    routing: "121000358"
---

### Payment Instructions

Please remit payment within 30 calendar days. Contact billing@rivera.im for questions.

C. Simple Documents & Running Headers/Footers (layout: simple)

Ideal for memos, technical specs, meeting notes, articles, and short policies where a cover page is unnecessary. You can customize running headers and footers directly:

---
layout: simple
title: Real-Time Sync Engine Spec
header-left: "Folio Engine V2"
header-right: "Confidential"
footer-left: "Revision 1.4"
footer-right: "Page {page} of {pages}"
theme: graphite
---

# Architecture Overview

This specification details the conflict-free replicated data types...

D. Mermaid Diagrams & KaTeX Math

Folio natively paginates Mermaid diagrams and LaTeX equations:

• Mermaid: Use standard fenced ```mermaid blocks. Folio colors them according to your active theme swatch!
• LaTeX: Write inline formulas with $E = mc^2$ and block formulas with $$ \frac{\partial f}{\partial x} = 2x $$.

3. Customizing Themes & Typography

Folio bundles 7 curated design presets crafted specifically for print pagination:

Per-Document Overrides

You can override any theme's color palette or font families inside your Markdown frontmatter:

---
theme: editorial
theme-overrides:
  accent: "#2563eb"
  font-heading: "Space Grotesk, sans-serif"
  font-body: "Inter, sans-serif"
  font-mono: "JetBrains Mono, monospace"
---

Page Breaks and Landscape Sections

Need explicit page control? Insert standard HTML helper tags anywhere in your Markdown body:

<!-- Force a clean page break before a new section -->
<div class="page-break"></div>

<!-- Rotate a wide financial table or diagram into landscape mode -->
<div class="page-landscape">

| Q1 Revenue | Q2 Revenue | Q3 Revenue | Q4 Revenue | Total YTD | Margin |
|:---|:---|:---|:---|:---|:---|
| $1,200,000 | $1,450,000 | $1,800,000 | $2,100,000 | $6,550,000 | 38.2% |

</div>

4. Model Context Protocol (MCP) Integration

Folio includes a native Model Context Protocol (MCP) server. This allows AI coding agents and LLM clients (such as Claude Desktop, Cursor, Google Antigravity, Cline, and Windsurf) to inspect document schemas, create branded documents, customize frontmatter, lint formatting, and compile pixel-perfect PDFs end-to-end.

Zero-Clone Connection via Native App Flag (--mcp)

You do not need to clone this repository, install Node.js, or hardcode development paths. If you have Folio.app installed in your Applications folder, launch it directly in headless MCP mode:

/Applications/Folio.app/Contents/MacOS/Folio --mcp

Pro Tip: Create a system-wide folio CLI shortcut
Run this one-line command in your terminal to symlink Folio to your PATH:

sudo ln -sf /Applications/Folio.app/Contents/MacOS/Folio /usr/local/bin/folio

Then you can simply configure your AI tools to run folio --mcp anywhere!

Client Configuration Snippets

Copy and paste the configuration block for your preferred AI client:

{
  "mcpServers": {
    "folio": {
      "command": "/Applications/Folio.app/Contents/MacOS/Folio",
      "args": ["--mcp"]
    }
  }
}

{
  "mcpServers": {
    "folio": {
      "command": "/Applications/Folio.app/Contents/MacOS/Folio",
      "args": ["--mcp"]
    }
  }
}

{
  "mcpServers": {
    "folio": {
      "command": "/Applications/Folio.app/Contents/MacOS/Folio",
      "args": ["--mcp"]
    }
  }
}

The 7 MCP Agent Tools

Custom Presets in .folio/presets/

When an agent or user registers a custom document format via folio_register_document_type, Folio saves it into .folio/presets/<id>.json in your repository root. These presets are automatically discovered on future runs across all agent sessions.

5. Development & Contributing

Contributing to Folio or running the app from source is straightforward:

Prerequisites

• macOS (Apple Silicon or Intel)
• Node.js 20 or newer
• pnpm 11+ (corepack enable && corepack prepare pnpm@latest --activate)

Cloning & Running Locally

# 1. Clone the repository
git clone https://github.com/carlosrivera/folio.git
cd folio

# 2. Install dependencies
pnpm install

# 3. Start development environment
pnpm dev

pnpm dev starts the Vite renderer server on localhost:5173 and launches the Electron application with hot reloading.

Running Tests & Verification

# Run Vitest unit tests (lib, diff, document parser, linting, mcp server)
pnpm test

# Run full project verification (TypeScript + Vitest + Render Tests + Editor Smoke)
pnpm check

# Run headless golden visual regression tests
pnpm test:render

# Test MCP server directly over stdio
pnpm mcp

Packaging macOS Releases Locally

Folio uses electron-builder to produce universal and signed macOS distributions:

# Build macOS distributables (.dmg and .zip) into dist-packaged/
pnpm dist:mac

# Build unpackaged directory app for inspection
pnpm dist:dir

Landing Page & Docs Development

# Run Astro docs & landing server locally
pnpm landing:dev

# Build static production site to landing/dist/
pnpm landing:build