Configuration Reference

MarkForge provides a fully type-safe, declarative configuration system. You can configure documents using markforge.config.ts, .markforgerc.json, markforge.config.yaml, or directly via Markdown frontmatter.

Configuration Hierarchy

MarkForge automatically discovers and resolves configuration using a strict 3-tier precedence hierarchy:

Markdown Frontmatter (Highest Priority)
        └── Project Config File (markforge.config.ts / .json / .yaml)
                └── Engine Default Settings (DEFAULT_CONFIG)

TypeScript Config Example (`markforge.config.ts`)

Using defineConfig with TypeScript Enums provides autocompletion and compile-time type validation:

import {
  defineConfig,
  OutputFormat,
  Theme,
  Orientation,
  PaperSizeEnum,
  SyntaxTheme,
  SignatureAlign,
  SignatureStyle,
} from "@masumdev/markforge";

export default defineConfig({
  // Target output formats
  to: [OutputFormat.DOCX, OutputFormat.PDF, OutputFormat.HTML, OutputFormat.TXT],

  // Output destination directory
  outputDir: ".temp/output",

  // Theme preset or custom ThemeProps
  theme: Theme.CORPORATE,

  // Page geometry
  orientation: Orientation.PORTRAIT,
  paperSize: PaperSizeEnum.A4,
  margins: {
    top: "3cm",
    bottom: "2.5cm",
    left: "2.5cm",
    right: "2.5cm",
  },

  // Cover Page Builder
  coverPage: {
    enabled: true,
    preset: "modern",
    logo: "./assets/company-logo.png",
    logoWidth: 140,
    badge: "CONFIDENTIAL SPECIFICATION",
    badgeColor: "#ECFDFD",
    badgeTextColor: "#0D998D",
    footerText: "Proprietary Document - Authorized Personnel Only",
  },

  // Back Cover / Closing Page
  backCover: {
    enabled: true,
    preset: "corporate",
    logo: "./assets/company-logo.png",
    logoWidth: 120,
    title: "Thank You",
    subtitle: "Enterprise Cross-Platform Document Solutions",
    company: "Masum Dev Technologies",
    address: "Jakarta, Indonesia",
    email: "contact@masumdev.com",
    phone: "+62 812 3456 7890",
    website: "https://react-native-library-docs.vercel.app",
    social: {
      github: "https://github.com/masumrpg",
    },
    copyright: "Copyright (c) {year} {company}. All Rights Reserved.",
  },

  // Running headers with per-zone styling & tokens
  header: {
    left: {
      text: "{company} - {title}",
      color: "#0D998D",
      fontSize: 9,
      bold: true,
    },
    center: "Technical Specification",
    right: {
      text: "v{version}",
      color: "#94A3B8",
      fontSize: 8.5,
      italic: true,
    },
    divider: true,
    dividerColor: "#CBD5E1",
  },

  // Running footers with dynamic page numbers
  footer: {
    left: {
      text: "Author: {author}",
      color: "#64748B",
      fontSize: 8.5,
    },
    center: {
      text: "{date}",
      color: "#94A3B8",
      fontSize: 8.5,
      italic: true,
    },
    right: {
      text: "Page {page} of {pages}",
      color: "#0D998D",
      fontSize: 9,
      bold: true,
    },
    divider: true,
    dividerColor: "#CBD5E1",
  },

  // Table of Contents & Heading Numbering
  toc: true,
  tocTitle: "TABLE OF CONTENTS",
  tocDepth: 3,
  numberHeadings: {
    enabled: true,
    depth: 3,
    skipH1: false,
  },

  // Math equation rendering
  math: true,

  // PDF Document Security & AES-256 Encryption
  security: {
    userPassword: "masumdev_secret",
    ownerPassword: "masumdev_admin",
    permissions: {
      printing: "highResolution",
      modifying: false,
      copying: true,
      annotating: true,
      fillingForms: true,
      contentAccessibility: true,
      documentAssembly: false,
    },
  },

  // Unselectable diagonal watermark
  watermark: {
    text: "CONFIDENTIAL DRAFT",
    color: "#E11D48",
    opacity: 0.1,
    fontSize: 52,
    rotate: -45,
  },

  // Document signatures and approval block
  signatureBlock: {
    align: SignatureAlign.SPACE_BETWEEN,
    style: SignatureStyle.BOX,
    spacingBefore: "2.5cm",
    items: [
      {
        title: "Prepared By",
        name: "{author}",
        role: "Principal Mobile Architect",
        date: "{date}",
      },
      {
        title: "Approved By",
        name: "Enterprise Architecture Board",
        role: "Chief Technology Officer",
        date: "{date}",
      },
    ],
  },

  // Code syntax highlighting
  syntaxTheme: SyntaxTheme.GITHUB_DARK,

  // Fallback metadata dictionary
  metadata: {
    title: "Document Reference Manual",
    author: "Ma'sum (@masumrpg)",
    company: "Masum Dev Technologies",
    version: "1.0.0",
    date: "2026-08-30",
  },
});

Detailed Configuration Properties

Target Output & Directories

Property	Type	Default	Description
`to`	`OutputFormat[]`	`['docx', 'pdf']`	Array of output file formats to compile: `OutputFormat.DOCX`, `OutputFormat.PDF`, `OutputFormat.HTML`, `OutputFormat.TXT`, `OutputFormat.PNG`.
`outputDir`	`string`	`'.'`	Destination folder for compiled document files. Created automatically if it does not exist.
`clean`	`boolean`	`false`	When `true`, removes existing compiled documents in `outputDir` prior to compilation.

Theming & Design System

Property	Type	Default	Description
`theme`	`Theme \| ThemeProps`	`Theme.CORPORATE`	Preset name (`Theme.CORPORATE`, `Theme.DEFAULT`, `Theme.ACADEMIC`, `Theme.GITHUB`, `Theme.MINIMAL`) or a custom `ThemeProps` object.
`syntaxTheme`	`SyntaxTheme`	`SyntaxTheme.GITHUB_DARK`	Syntax highlighting palette: `SyntaxTheme.GITHUB_DARK`, `SyntaxTheme.GITHUB_LIGHT`, `SyntaxTheme.DRACULA`, `SyntaxTheme.MONOKAI`, `SyntaxTheme.NORD`, `SyntaxTheme.ONE_DARK`, `SyntaxTheme.SOLARIZED_DARK`, `SyntaxTheme.SOLARIZED_LIGHT`.
`css`	`string \| string[]`	`undefined`	Path or array of paths to external CSS stylesheets to inject into PDF and HTML outputs.
`customCss`	`string`	`undefined`	Raw CSS text string injected into the `<head>` of the compiled document.

Custom `ThemeProps` Schema

export interface ThemeProps {
  primaryColor?: string;     // Accent color (e.g. "#0D998D")
  primaryDark?: string;      // Darker shade for borders (e.g. "#008073")
  primaryLight?: string;     // Lighter tint for badges (e.g. "#D9F1F0")
  backgroundColor?: string;  // Canvas background (e.g. "#FFFFFF")
  textColor?: string;        // Body text color (e.g. "#0F172A")
  textMuted?: string;        // Secondary/muted text (e.g. "#64748B")
  borderColor?: string;      // Container borders (e.g. "#E2E8F0")
  cardBackground?: string;   // Card fills (e.g. "#F8FAFC")
  fontFamily?: string;       // Primary font stack (e.g. "'Inter', sans-serif")
  fontMono?: string;         // Monospace font stack (e.g. "'Fira Code', monospace")
}

Page Setup & Geometry

Property	Type	Default	Description
`orientation`	`Orientation`	`Orientation.PORTRAIT`	Document page orientation: `Orientation.PORTRAIT` or `Orientation.LANDSCAPE`.
`paperSize`	`PaperSizeEnum`	`PaperSizeEnum.A4`	Standard paper size: `PaperSizeEnum.A4`, `PaperSizeEnum.LETTER`, `PaperSizeEnum.LEGAL`, `PaperSizeEnum.A3`, `PaperSizeEnum.A5`.
`margins`	`PageMargins`	`{ top: '2.5cm', bottom: '2.5cm', left: '2.5cm', right: '2.5cm' }`	Page margins with standard units (`cm`, `mm`, `in`, `pt`).
`breakBeforeHeadings`	`number[]`	`[1]`	Heading levels that trigger an automatic hard page break (`[1]` breaks before every H1).
`embedImages`	`boolean`	`true`	When `true`, all referenced images (local files and remote URLs) are Base64-inlined into the output.

Headers and footers support three independent positional zones (left, center, right). Each zone can be defined as a plain string or a detailed HeaderFooterSlot object:

export interface HeaderFooterSlot {
  text: string;           // Template string with tokens ({title}, {author}, {page}, {pages}, etc.)
  color?: string;         // Hex color code (e.g. "#0D998D")
  fontSize?: number;      // Font size in points (e.g. 9)
  fontFamily?: string;    // Custom font family (e.g. "Segoe UI")
  bold?: boolean;         // Bold font weight
  italic?: boolean;       // Italic font style
}

Available Dynamic Tokens

{title}: Document title resolved from metadata or first H1
{subtitle}: Document subtitle
{author}: Author name(s)
{company}: Organization or company name
{version}: Document version string
{date}: Document publication date
{year}: Current four-digit calendar year
{page}: Current page number (PDF and DOCX)
{pages}: Total document page count (PDF and DOCX)

Table of Contents & Heading Numbering

Property	Type	Default	Description
`toc`	`boolean`	`true`	Enable or disable automated Table of Contents generation.
`tocTitle`	`string`	`'TABLE OF CONTENTS'`	Title header displayed above the Table of Contents card.
`tocDepth`	`number`	`3`	Maximum heading level depth included in the TOC (1 to 6).
`numberHeadings`	`boolean \| NumberHeadingsOptions`	`false`	Enable automated decimal section numbering (`1.`, `1.1.`, `1.1.1.`).

// Detailed numberHeadings options
numberHeadings: {
  enabled: true,
  depth: 3,           // Number headings down to H3
  skipH1: false,      // Set to true to leave main document H1 unnumbered
  prefix: "",         // Optional prefix (e.g. "SEC-")
}

Cover Page Builder (`coverPage`)

Generates a dedicated, unnumbered title page before the main document content with full custom styling support:

coverPage: {
  enabled: true,
  preset: "modern",                         // "modern" | "corporate-split" | "minimal" | "card"
  title: "Annual Architecture Report",     // Fallback to {title}
  subtitle: "Enterprise Technical Roadmap", // Fallback to {subtitle}
  author: "Ma'sum",                         // Fallback to {author}
  company: "Masum Dev Technologies",       // Fallback to {company}
  date: "2026-08-30",                       // Fallback to {date}
  version: "1.0.0",                         // Fallback to {version}
  logo: "./assets/company-logo.png",        // Local path or URL
  logoWidth: 140,                           // Logo display width in px
  badge: "CONFIDENTIAL",                    // Top-right status badge text
  badgeColor: "#ECFDFD",                    // Badge background color
  badgeTextColor: "#0D998D",                // Badge text color
  footerText: "Strictly Confidential",      // Bottom disclaimer text
  backgroundColor: "#0A192F",               // Optional custom background color
  bgGradient: "linear-gradient(135deg, #0A192F 0%, #172A45 100%)", // Custom CSS gradient
  titleColor: "#FFFFFF",                    // Custom title color
  subtitleColor: "#64FFDA",                 // Custom subtitle color
  textColor: "#8892B0",                     // Custom text color
  accentColor: "#64FFDA",                   // Custom accent color
}

Back Cover / Closing Page (`backCover`)

Generates an isolated closing back cover card at the end of the document with symmetric styling properties matching coverPage:

backCover: {
  enabled: true,
  preset: "corporate",                      // "modern" | "corporate" | "minimal" | "contact-card"
  title: "Thank You",
  subtitle: "Next-Gen Engineering Solutions",
  company: "Masum Dev Technologies",
  address: "Jakarta, Indonesia",
  email: "contact@masumdev.com",
  phone: "+62 812 3456 7890",
  website: "https://react-native-library-docs.vercel.app",
  logo: "./assets/company-logo.png",
  logoWidth: 120,
  social: {
    github: "https://github.com/masumrpg",
  },
  copyright: "Copyright (c) {year} {company}. All Rights Reserved.",
  backgroundColor: "#0A192F",               // Custom background color
  bgGradient: "linear-gradient(135deg, #0A192F 0%, #172A45 100%)", // Custom gradient
  titleColor: "#FFFFFF",                    // Custom title color
  subtitleColor: "#64FFDA",                 // Custom subtitle color
  textColor: "#8892B0",                     // Custom text color
  accentColor: "#64FFDA",                   // Custom accent color
}

PDF Security & Password Encryption (`security`)

Encrypts the PDF using ISO 32000-2 AES-256 standards:

security: {
  userPassword: "masumdev_secret", // Password required to open the PDF
  ownerPassword: "masumdev_admin",  // Master password required to modify permissions
  permissions: {
    printing: "highResolution",     // "highResolution" | "lowResolution" | false
    modifying: false,               // Allow editing document contents
    copying: true,                  // Allow extracting text and images
    annotating: true,               // Allow adding comments and form annotations
    fillingForms: true,             // Allow filling in interactive form fields
    contentAccessibility: true,     // Allow screen readers to extract content
    documentAssembly: false,        // Allow inserting, rotating, or deleting pages
  },
}

Watermark (`watermark`)

Renders a diagonal background watermark on all content pages (excluding the cover and back cover):

watermark: {
  text: "CONFIDENTIAL DRAFT",
  color: "#E11D48",
  opacity: 0.10,
  fontSize: 52,
  rotate: -45,                      // Negative degrees slope upwards from bottom-left to top-right
}

Signatures & Approval Block (`signatures`)

Appends a formal multi-signatory approval grid to the document:

signatures: {
  align: SignatureAlign.SPACE_BETWEEN, // "left" | "center" | "right" | "space-between"
  style: SignatureStyle.BOX,           // "line" | "box" | "clean"
  spacingBefore: "2.5cm",
  borderColor: "#CBD5E1",
  items: [
    {
      title: "Prepared By",
      name: "Ma'sum",
      role: "Lead Mobile Architect",
      date: "{date}",
      image: "./assets/signature-masum.png", // Optional signature image
      signatureHeight: 48,
    },
    {
      title: "Approved By",
      name: "Enterprise Architecture Board",
      role: "Chief Technology Officer",
      date: "{date}",
    },
  ],
}

Configuration Reference

Configuration Hierarchy

TypeScript Config Example (markforge.config.ts)

Detailed Configuration Properties

Target Output & Directories

Theming & Design System

Custom ThemeProps Schema

Page Setup & Geometry

Header & Footer Slots

Available Dynamic Tokens

Table of Contents & Heading Numbering

Cover Page Builder (coverPage)

Back Cover / Closing Page (backCover)

PDF Security & Password Encryption (security)

Watermark (watermark)

Signatures & Approval Block (signatures)