Why We Use Markdown Instead of PDF Templates for Contract Signing

The problem with PDF templates

Every e-signature platform I evaluated before building Signbee follows the same pattern: you create a document template in their web UI, position signature fields by dragging them onto a PDF preview, define merge fields for dynamic content, and then call their API with a template ID and field values.

This model has three fundamental problems for developers:

Templates live in a vendor's dashboard, not in your codebase. Your contract templates are stored in DocuSign's cloud, HelloSign's cloud, or PandaDoc's cloud. They're not in your git repo. When a developer changes a clause, there's no pull request, no code review, no commit history. When your legal team asks "who changed the payment terms in the freelance agreement?" you check an activity log in a third-party dashboard — if one exists.

Templates are binary. A PDF is not human-readable text. You can't git diff two versions of a PDF template. You can't grep for a specific clause across all your templates. You can't write a CI check that verifies all contracts contain your updated liability language. Binary files are opaque — they break every tool developers use for managing text.

Templates require a GUI step that breaks automation. Before your code can send a document, someone must manually create the template in a web interface. That means your CI/CD pipeline can't create new document types. Your AI agent can't draft a custom agreement. Your onboarding flow can't generate a personalised contract without a pre-existing template for every variation.

The markdown alternative

Signbee takes a fundamentally different approach. Instead of uploading PDFs or referencing template IDs, you send markdown text directly in the API request. Signbee converts it to a professionally formatted PDF server-side, appends a signature field, and sends it to the recipient for signing.

const response = await fetch("https://signb.ee/api/v1/send", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer sb_live_your_api_key",
  },
  body: JSON.stringify({
    markdown: `# Freelance Agreement

## Parties

This agreement is between **Acme Corp** ("Client") and
**Alex Chen** ("Contractor").

## Scope of Work

Contractor will provide frontend development services
for the Client's web application, including:

- React component development
- Performance optimization
- Code review and documentation

## Compensation

Client will pay Contractor **$5,000 per month**, invoiced
on the 1st of each month, payable within 14 days.

## Term

This agreement begins on **June 1, 2026** and continues
on a month-to-month basis until terminated by either
party with 30 days written notice.

## Confidentiality

Contractor agrees to keep all Client materials,
codebases, and business information confidential.`,
    recipient_name: "Alex Chen",
    recipient_email: "alex@studio.co",
    sender_name: "Michael Beckett",
  }),
});

const { document_id, signing_url } = await response.json();

No template ID. No merge fields. No dashboard step. The content is the document.

Dynamic content becomes trivial

When your document format is a string, generating dynamic content is just string interpolation — the thing every programming language already does:

function generateContract(
  clientName: string,
  contractorName: string,
  rate: number,
  startDate: string
): string {
  return `# Freelance Agreement

## Parties
This agreement is between **${clientName}** ("Client")
and **${contractorName}** ("Contractor").

## Compensation
Client will pay Contractor **$${rate.toLocaleString()}
per month**, invoiced on the 1st of each month.

## Term
This agreement begins on **${startDate}** and continues
on a month-to-month basis.
`;
}

// Usage — no template IDs, no merge fields
const markdown = generateContract(
  "Acme Corp", "Alex Chen", 5000, "June 1, 2026"
);

With PDF templates, you'd need to create the template first, define merge fields (often with arcane positioning coordinates), then pass field values through the API. With markdown, you write a function. That function can accept any parameters. It can include conditional sections. It can pull data from a database. It's code — and code is infinitely flexible.

Version control changes everything

This is the advantage I didn't fully appreciate until I started using it in production. When your contract templates are markdown files in a git repository, you get:

For teams using the free agreement templates we provide, this means you fork the template into your repo and customise it with full version history from day one.

Why this makes Signbee AI-native

This is the connection I want to make explicit, because it's the reason markdown-first architecture matters most in 2026.

LLMs output text. When you ask Claude to "draft an NDA for Jane Smith at Acme Corp," it generates markdown. Not a PDF. Not an XML envelope definition. Not a base64-encoded binary blob. It produces the exact format Signbee accepts.

This is why the signbee-mcp server works so naturally. The agent's native output format (markdown) maps directly to Signbee's input format. There's no transformation step. No template lookup. No binary conversion. The agent thinks in text, writes in text, and sends text to an API that accepts text.

Try doing this with DocuSign. Your agent would need to: find the right template ID (how?), map natural language to merge field names (which ones?), handle the coordinate-based tab positioning (where exactly?), and manage the OAuth token (expired again?). The impedance mismatch between how LLMs work and how template-based APIs work is enormous.

The tradeoffs we accepted

Honesty requires acknowledging what we give up with this approach:

No pixel-perfect layout control. You can't position a logo at exactly 72px from the top-left corner. You can't use custom fonts. You can't create complex multi-column layouts. If you need a document that looks exactly like your branded letterhead, you need a PDF template. Signbee's PDFs look clean and professional, but they look like Signbee's formatting, not yours.

No visual editor for non-developers. A product manager at DocuSign can drag-and-drop to create templates. With Signbee, someone needs to write markdown — which is trivial for developers but may be unfamiliar for non-technical users. That said, our contract template library covers the most common document types, and markdown is learnable in about 10 minutes.

No pre-positioned signature fields. In DocuSign, you can place a signature tab at a specific location on a specific page. In Signbee, the signature field is automatically appended at the end of the document. For simple agreements — NDAs, freelance contracts, offer letters, waivers — this is fine. For complex multi-page documents requiring signatures on specific pages, it's a limitation.

Who this architecture is for

The philosophical argument

There's a deeper principle here that goes beyond practicality. Documents are data, not design artifacts. The purpose of a contract is to capture an agreement between parties — the content matters, not the font. An NDA signed in Helvetica Neue is legally identical to one signed in Times New Roman.

The entire template-builder paradigm treats documents as visual objects that need to be designed. Signbee treats them as structured text that needs to be signed. The visual rendering is a presentation concern handled server-side, not a creation concern handled by the developer.

This is the same shift that happened with web content: from WYSIWYG editors to markdown-based CMSs. The same shift is happening with document signing, and we're building for that future.

For more on how this connects to the broader AI agent ecosystem, see our guide on agents and document signing.

Frequently Asked Questions

Last updated: May 22, 2026 · Michael Beckett is the founder of Signbee and B2bee Ltd.