Document Generation Overview

Json2doc transforms JSON configurations into professional documents. This guide explains the core JSON structure, configuration options, and features that form the foundation of all document generation.

Basic JSON Structure

Every json2doc configuration follows this hierarchical structure:

{
  "document": {
    "type": "pdf",
    "filename": "my-document",
    "title": "Document Title",
    "author": "Author Name",
    "size": "A4"
  },
  "variables": {
    "companyName": "Acme Corp"
  },
  "defaults": {
    "fontFamily": "Arial",
    "fontSize": 11,
    "color": "#000000",
    "lineHeight": 1.5,
    "header": {
      "left": "{{companyName}}",
      "center": "Document Title",
      "right": "Page {{pageNumber}}"
    },
    "footer": {
      "left": "2025",
      "center": "",
      "right": "{{pageNumber}} of {{totalPages}}"
    },
    "styles": {
      "h1": { "fontSize": 24, "fontWeight": "bold", "color": "#0066cc" },
      "text": { "fontSize": 11, "lineHeight": 1.4 }
    }
  },
  "sections": [
    {
      "type": "flow",
      "content": [
        { "type": "h1", "text": "Main Title" },
        { "type": "text", "text": "Document content goes here." }
      ]
    }
  ]
}

The structure consists of four main components:

1. document - Output format and page configuration
2. variables - Dynamic content placeholders
3. defaults - Global styling and layout settings
4. sections - Document content organized in sections

Document Configuration

The document object defines the output format, metadata, and page layout settings.

Basic Properties

Property	Type	Required	Default	Description
type	string	✅	-	Output format: "pdf" or "docx"
filename	string	❌	"document"	Output filename (without extension)
title	string	❌	-	Document title (appears in metadata)
author	string	❌	-	Document author
subject	string	❌	-	Document subject
keywords	array	❌	-	Array of keywords (max 10)

Page Layout

Property	Type	Default	Description
size	string	"A4"	Page size: "A4", "A3", "A5", "Letter", "Legal"
orientation	string	"portrait"	Page orientation: "portrait" or "landscape"
marginTop	number	2.54	Top margin in cm
marginRight	number	2.54	Right margin in cm
marginBottom	number	2.54	Bottom margin in cm
marginLeft	number	2.54	Left margin in cm

Example Configuration

{
  "document": {
    "type": "pdf",
    "filename": "business-report-2024",
    "title": "Annual Business Report",
    "author": "Finance Department",
    "subject": "Annual financial performance and outlook",
    "keywords": ["business", "report", "2024", "finance", "annual"],
    "size": "A4",
    "orientation": "portrait",
    "marginTop": 2.0,
    "marginRight": 2.5,
    "marginBottom": 2.0,
    "marginLeft": 2.5
  }
}

Variables System

Variables enable dynamic content throughout your document using mustache template syntax {{variableName}}.

Built-in Variables

Json2doc provides two built-in variables that are automatically available:

Variable	Description	Example Output
{{pageNumber}}	Current page number	1, 2, 3, etc.
{{totalPages}}	Total number of pages in document	15, 23, etc.

Custom Variables

Define custom variables in the variables object:

{
  "variables": {
    "companyName": "Acme Corporation",
    "year": "2024",
    "reportDate": "March 15, 2024",
    "department": "Sales",
    "revenue": "1,250,000",
    "isQuarterly": true
  }
}

Using Variables in Content

Variables can be used in any text content:

{
  "type": "h1",
  "text": "{{companyName}} {{department}} Report - {{year}}"
}

{
  "type": "text",
  "text": "This report was generated on {{reportDate}} and covers {{companyName}}'s performance with total revenue of ${{revenue}}."
}

Variable Properties

Property	Type	Max Length	Description
Variable name	string	50 chars	Must start with letter, contain only letters, numbers, underscore
Variable value	string	1000 chars	The replacement text

Headers and Footers

Headers and footers use a flexible three-column layout system with support for multiple content types including text, images, and complex multi-line objects. They support variables, markdown formatting, and advanced alignment options.

Content Types

Headers and footers support three different content types:

1. Simple Strings - Basic text with markdown and variable support
2. Text Objects - Multi-line content with individual line styling
3. Image Objects - Logos and graphics with size control

Multi-Column Schema

Each header and footer is divided into three columns with intelligent layout:

{
  "defaults": {
    "header": {
      "left": "Left column content",
      "center": "Center column content", 
      "right": "Right column content",
      "align": "center",
      "excludeFirstPage": false
    },
    "footer": {
      "left": "Left column content",
      "center": "Center column content",
      "right": "Right column content",
      "align": "right", 
      "excludeFirstPage": true
    }
  }
}

Simple String Content

Basic text content with markdown and variable support:

{
  "header": {
    "left": "**{{companyName}}**",
    "center": "Annual Report {{year}}",
    "right": "Page {{pageNumber}} of {{totalPages}}"
  }
}

Text Objects

Multi-line content with individual styling for each line:

{
  "header": {
    "center": {
      "type": "text",
      "content": [
        {
          "text": "{{reportType}} {{year}}",
          "fontSize": 14,
          "fontWeight": "bold",
          "color": "#0066cc"
        },
        {
          "text": "*{{department}} Department*",
          "fontSize": 10,
          "color": "#666666"
        }
      ]
    }
  }
}

Image Objects

Logos and graphics with size and positioning control:

{
  "header": {
    "right": {
      "type": "image",
      "src": "/path/to/logo.png",
      "width": 40,
      "height": 40,
      "alt": "Company Logo"
    }
  }
}

Global Alignment Override

The align property overrides default column positioning for all content:

{
  "header": {
    "left": "Left content",
    "center": "Center content",
    "right": "Right content",
    "align": "center"  // All content will be centered
  }
}

Alignment Options:

• "left" - All content left-aligned
• "center" - All content centered
• "right" - All content right-aligned
• No align property - Default positioning (left/center/right)

Intelligent Column Widths

The system automatically adjusts column widths based on content:

• Single content: Uses full page width with specified alignment
• Two contents: Equal 50% / 50% distribution
• Three contents: Equal 33% / 33% / 33% distribution

Header/Footer Properties

Property	Type	Description
left	string/object	Left column content (string, text object, or image object)
center	string/object	Center column content (string, text object, or image object)
right	string/object	Right column content (string, text object, or image object)
align	string	Global alignment override: "left", "center", "right"
excludeFirstPage	boolean	Exclude header/footer from first page (default: false)

Text Object Properties

Property	Type	Description
type	string	Must be "text"
content	array	Array of text line objects

Text Line Properties

Property	Type	Description
text	string	Text content (supports variables and markdown)
fontSize	number	Font size in points
fontWeight	string	"normal" or "bold"
fontStyle	string	"normal" or "italic"
color	string	Text color in hex format
fontFamily	string	Font family name

Image Object Properties

Property	Type	Description
type	string	Must be "image"
src	string	Image path (local or remote)
width	number	Image width in points
height	number	Image height in points
alt	string	Alternative text description

Word (DOCX) Limitation

Word documents (docx format) do not support hyperlinks in headers and footers. While you can include markdown link syntax like [Company Website](https://acme.com) in your configuration, it will be rendered as plain text in Word documents. Links work normally in PDF documents.

Enhanced Header/Footer Example

PDF Preview

Show complete JSON configuration

{
  "document": {
    "type": "pdf",
    "filename": "enhanced-headers-footers-demo",
    "title": "Enhanced Headers and Footers Demo"
  },
  "variables": {
    "companyName": "Acme Corporation",
    "year": "2024",
    "department": "Engineering",
    "reportType": "Annual Report",
    "version": "v2.1"
  },
  "defaults": {
    "fontFamily": "Arial",
    "fontSize": 11,
    "color": "#333333",
    "header": {
      "left": "**{{companyName}}**",
      "center": {
        "type": "text",
        "content": [
          {
            "text": "{{reportType}} {{year}}",
            "fontSize": 14,
            "fontWeight": "bold",
            "color": "#0066cc"
          },
          {
            "text": "*{{department}} Department*",
            "fontSize": 10,
            "color": "#666666"
          }
        ]
      },
      "right": {
        "type": "image",
        "src": "/image/2025-10-31/cmh107bik0001116um9xyurjo/137ab8bb-21d2-473f-aa69-35fc86631a74.png",
        "width": 30,
        "alt": "Company Logo"
      },
      "excludeFirstPage": false
    },
    "footer": {
      "left": {
        "type": "text",
        "content": [
          {
            "text": "CONFIDENTIAL",
            "fontSize": 8,
            "fontWeight": "bold",
            "color": "#ff0000"
          },
          {
            "text": "Internal Use Only",
            "fontSize": 7,
            "color": "#999999"
          }
        ]
      },
      "center": "Page {{pageNumber}} of {{totalPages}}",
      "right": {
        "type": "text",
        "content": [
          {
            "text": "Version {{version}}",
            "fontSize": 8,
            "fontWeight": "bold",
            "color": "#0066cc"
          },
          {
            "text": "Generated: 2024-01-15",
            "fontSize": 7,
            "color": "#666666"
          }
        ]
      },
      "align": "center",
      "excludeFirstPage": false
    }
  },
  "sections": [
    {
      "type": "page",
      "align": "center",
      "content": [
        {
          "type": "h1",
          "text": "{{companyName}}",
          "fontSize": 28,
          "color": "#0066cc",
          "align": "center"
        },
        {
          "type": "h2",
          "text": "{{reportType}} {{year}}",
          "fontSize": 20,
          "color": "#333333",
          "align": "center"
        },
        {
          "type": "text",
          "text": "*{{department}} Department*",
          "fontSize": 16,
          "color": "#666666",
          "align": "center"
        },
        {
          "type": "image",
          "src": "/image/2025-10-31/cmh107bik0001116um9xyurjo/efa92fae-411c-489b-b71e-d6fca197ca65.png",
          "width": 200,
          "height": 50,
          "align": "center"
        }
      ]
    }
  ]
}

This example demonstrates:

• Header with mixed content: Company name (string), multi-line title (text object), and logo (image)
• Footer with alignment override: All footer content centered using "align": "center"
• Multi-line text objects: Individual styling for each line
• Image integration: Logos with specified dimensions
• Variable usage: Dynamic content throughout
• Single page layout: Title page with centered content

Defaults System

The defaults object defines global styling, spacing, and formatting rules that apply throughout your document. Individual elements can override these defaults when needed.

Global Properties

Property	Type	Default	Description
fontFamily	string	"Arial"	Default font family for all elements
fontSize	number	11	Default font size in points
color	string	"#000000"	Default text color in hex format
lineHeight	number	1.5	Default line height multiplier

Element-Specific Styles

Define default styles for each element type:

{
  "defaults": {
    "fontFamily": "Arial",
    "fontSize": 11,
    "color": "#333333",
    "lineHeight": 1.4,
    "spacing": {
      "before": {
        "h1": 24, "h2": 20, "h3": 16, "text": 0, "table": 15
      },
      "after": {
        "h1": 18, "h2": 14, "h3": 12, "text": 10, "table": 15
      }
    },
    "styles": {
      "h1": {
        "fontSize": 28,
        "fontWeight": "bold",
        "color": "#0066cc",
        "align": "center"
      },
      "h2": {
        "fontSize": 22,
        "fontWeight": "bold",
        "color": "#0077dd"
      },
      "h3": {
        "fontSize": 18,
        "fontWeight": "bold",
        "color": "#333333"
      },
      "text": {
        "fontSize": 11,
        "lineHeight": 1.4,
        "align": "justify"
      },
      "text2": {
        "fontSize": 9,
        "color": "#666666",
        "align": "center"
      },
      "table": {
        "borders": {
          "outer": {
            "width": 1,
            "color": "#333333",
            "style": "solid"
          },
          "inner": {
            "width": 0.5,
            "color": "#999999",
            "style": "solid"
          }
        },
        "header": {
          "backgroundColor": "#f0f0f0",
          "color": "#000000",
          "fontSize": 12,
          "fontWeight": "bold",
          "fontStyle": "normal",
          "align": "center"
        },
        "rows": {
          "backgroundColor": "#ffffff",
          "color": "#333333",
          "fontSize": 11,
          "fontWeight": "normal",
          "fontStyle": "normal",
          "align": "left",
          "alternateBackgroundColor": "#f8f9fa"
        },
        "cellPadding": {
          "top": 8,
          "right": 8,
          "bottom": 8,
          "left": 8
        }
      }
    }
  }
}

Table Default Styles

The table style in defaults allows you to set consistent styling for all tables in your document. Individual tables can override these defaults as needed.

Table Style Properties

Section	Property	Type	Description
borders.outer	width	number	Outer border width in points
	color	string	Outer border color (hex format)
	style	string	Border style: "solid", "dashed", "dotted"
borders.inner	width	number	Inner border width in points
	color	string	Inner border color (hex format)
	style	string	Border style: "solid", "dashed", "dotted"
header	backgroundColor	string	Header background color
	color	string	Header text color
	fontSize	number	Header font size in points
	fontWeight	string	"normal" or "bold"
	fontStyle	string	"normal" or "italic"
	align	string	"left", "center", or "right"
rows	backgroundColor	string	Row background color
	alternateBackgroundColor	string	Alternate row color (zebra stripes)
	color	string	Row text color
	fontSize	number	Row font size in points
	fontWeight	string	"normal" or "bold"
	fontStyle	string	"normal" or "italic"
	align	string	"left", "center", or "right"
cellPadding	top	number	Top padding in points
	right	number	Right padding in points
	bottom	number	Bottom padding in points
	left	number	Left padding in points

Style Override Example

Elements can override default styles:

{
  "sections": [
    {
      "type": "flow",
      "content": [
        {
          "type": "h1",
          "text": "This uses default h1 styling"
        },
        {
          "type": "h1", 
          "text": "This overrides the default color",
          "color": "#ff0000",
          "align": "left"
        },
        {
          "type": "text",
          "text": "This uses default text styling"
        },
        {
          "type": "text",
          "text": "This text has custom styling",
          "fontSize": 14,
          "fontWeight": "bold",
          "color": "#0066cc",
          "spacing": {
            "before": 20,
            "after": 20
          }
        }
      ]
    }
  ]
}

Available Style Properties

Property	Type	Values	Description
fontFamily	string	Font name	Font family (see Fonts section)
fontSize	number	6-72	Font size in points
fontWeight	string	"normal", "bold"	Font weight
color	string	Hex color	Text color (#000000 format)
align	string	"left", "center", "right", "justify"	Text alignment
lineHeight	number	0.5-3.0	Line height multiplier

Fonts

Json2doc supports a comprehensive set of fonts available in the Docker container environment. All fonts are pre-installed and ready to use.

Font Categories

The system includes several font categories:

• Liberation fonts - Open source alternatives to common fonts
• Noto fonts - Comprehensive Unicode support for international text
• DejaVu fonts - High-quality Unicode fonts
• Roboto fonts - Modern sans-serif family
• System fonts - Standard document fonts

Font Usage

Specify fonts using the exact font family name:

{
  "defaults": {
    "fontFamily": "Liberation Sans"
  }
}

{
  "type": "h1",
  "text": "Custom Font Heading",
  "fontFamily": "Roboto"
}

Available Fonts (Click to expand)

Core Document Fonts

• Liberation Sans - Clean sans-serif (Arial alternative)
• Liberation Serif - Traditional serif (Times New Roman alternative)
• Liberation Mono - Monospace (Courier New alternative)
• Liberation Sans Narrow - Condensed sans-serif

Modern Fonts

• Roboto - Google's flagship font
• Roboto Condensed - Condensed version of Roboto
• Roboto Slab - Slab serif version
• Open Sans - Friendly sans-serif
• Open Sans Condensed - Condensed version
• Lato - Humanist sans-serif

Unicode & International Fonts

• Noto Sans - Universal sans-serif with extensive language support
• Noto Serif - Universal serif with extensive language support
• Noto Sans Mono - Monospace with Unicode support
• Noto Sans Display - Display version for headings
• Noto Serif Display - Display serif for headings

Language-Specific Fonts

• Noto Sans Arabic - Arabic script support
• Noto Sans Armenian - Armenian script
• Noto Sans Bengali - Bengali script
• Noto Sans Cherokee - Cherokee script
• Noto Sans Devanagari - Devanagari script (Hindi, Sanskrit)
• Noto Sans Ethiopic - Ethiopic script
• Noto Sans Georgian - Georgian script
• Noto Sans Gujarati - Gujarati script
• Noto Sans Gurmukhi - Gurmukhi script (Punjabi)
• Noto Sans Hebrew - Hebrew script
• Noto Sans Kannada - Kannada script
• Noto Sans Khmer - Khmer script (Cambodian)
• Noto Sans Lao - Lao script
• Noto Sans Malayalam - Malayalam script
• Noto Sans Myanmar - Myanmar script (Burmese)
• Noto Sans Oriya - Oriya script
• Noto Sans Sinhala - Sinhala script (Sri Lankan)
• Noto Sans Tamil - Tamil script
• Noto Sans Telugu - Telugu script
• Noto Sans Thai - Thai script

CJK (Chinese, Japanese, Korean) Fonts

• Noto Sans CJK HK - Hong Kong Chinese
• Noto Sans CJK JP - Japanese
• Noto Sans CJK KR - Korean
• Noto Sans CJK SC - Simplified Chinese
• Noto Sans CJK TC - Traditional Chinese
• Noto Serif CJK HK - Hong Kong Chinese serif
• Noto Serif CJK JP - Japanese serif
• Noto Serif CJK KR - Korean serif
• Noto Serif CJK SC - Simplified Chinese serif
• Noto Serif CJK TC - Traditional Chinese serif

Classic & System Fonts

• DejaVu Sans - High-quality sans-serif
• DejaVu Serif - High-quality serif
• DejaVu Sans Mono - High-quality monospace
• Nimbus Sans - PostScript sans-serif
• Nimbus Roman - PostScript serif
• Nimbus Mono PS - PostScript monospace
• URW Bookman - Classic serif
• URW Gothic - Gothic sans-serif

Specialty Fonts

• Noto Color Emoji - Color emoji support
• Noto Music - Musical notation
• Noto Sans Symbols - Symbol characters
• Noto Sans Symbols2 - Additional symbols
• OpenSymbol - OpenOffice symbol font
• Standard Symbols PS - PostScript symbols

Font Recommendations

Use Case	Recommended Fonts
Body Text	Liberation Sans, Noto Sans, Open Sans
Headings	Roboto, Liberation Sans, Noto Sans Display
Code/Data	Liberation Mono, Noto Sans Mono, DejaVu Sans Mono
International	Noto Sans (with appropriate script variant)
Print Documents	Liberation Serif, Noto Serif

Section Types

Json2doc supports two main section types that control document layout and content flow.

Flow Sections

Flow sections contain content that flows naturally across multiple pages, automatically handling page breaks and maintaining consistent formatting.

Properties

Property	Type	Default	Description
type	string	-	Must be "flow"
newPage	boolean	true	Start section on a new page
content	array	-	Array of content elements (1-200 items)

Page Break Control

Flow sections start on a new page by default (newPage: true). Set newPage: false to continue content on the same page as the previous section.

Example

{
  "type": "flow",
  "newPage": false,
  "content": [
    { "type": "h1", "text": "Introduction" },
    { "type": "text", "text": "This content flows naturally across pages." },
    { "type": "h2", "text": "Background" },
    { "type": "text", "text": "Additional content continues flowing." },
    {
      "type": "table",
      "headers": ["Column 1", "Column 2"],
      "rows": [["Data 1", "Data 2"], ["Data 3", "Data 4"]]
    }
  ]
}

Use cases:

• Main document content
• Articles and reports
• Sequential information
• Multi-page content

Page Sections

Page sections create dedicated pages with specific layouts and positioning control.

Properties

Property	Type	Default	Description
type	string	-	Must be "page"
align	string	"top"	Vertical alignment: "top", "center", "bottom"
startY	number	-	Y position in cm (overrides align)
content	array	-	Array of content elements (1-100 items)

Example

{
  "type": "page",
  "align": "center",
  "content": [
    { "type": "h1", "text": "Title Page" },
    { "type": "text", "text": "Document Subtitle", "align": "center" },
    { "type": "image", "src": "/logo.png", "align": "center" },
    { "type": "text", "text": "Version 2.0", "align": "center" }
  ]
}

Custom Positioning

Use startY for precise positioning:

{
  "type": "page", 
  "startY": 10.5,
  "content": [
    { "type": "h1", "text": "Positioned at 10.5cm from top" }
  ]
}

Use cases:

• Title pages
• Cover pages
• Certificates
• Forms with specific layouts

Section Comparison

Feature	Flow Section	Page Section
Page handling	Multi-page flow	Single page
Content limit	200 elements	100 elements
Positioning	Sequential	Custom positioning
Page breaks	Automatic	Manual (new page per section)
Best for	Main content	Special layouts

Next Steps

Now that you understand the core structure and configuration options, explore these guides:

• Elements - Detailed documentation for all content elements with styling options
• Builder - Interactive document building approach for AI agents
• Examples - Complete document examples and templates
• Styling - Advanced styling techniques and best practices

Ready to create your first document? Start with the Elements guide to learn about all available content types.