Code Elements

This page shows how to use the code element in json2doc.

The code element can either be rendered as plain monospace text in DOCX or as a PNG image with syntax highlighting.

Code Properties & Defaults

Code Element Properties

Property	Type	Required	Description	Default
type	string	✓	Element type: "code"	-
code	string	✓	Code content to render or display	-
language	string	✗	Programming language key for syntax highlighting, e.g. "javascript", "python", "json"	Auto-detected when omitted
renderAsImage	boolean	✗	If true, the code block is rendered as a PNG image and then inserted like an image. If false, it is rendered as monospace text in DOCX.	false
backgroundColor	string	✗	Background color for the rendered code image in hex format (e.g. "#1E293B"). Only used when renderAsImage is true.	#1e1e1e (dark theme)
width	number	✗	Rendered code image width in pixels (10–2000). The final width is clamped to the available page width (page width minus margins and a small inner padding). Only used when renderAsImage is true.	Auto (clamped to page width)
align	string	✗	Code block alignment: "left", "center", "right". For images this controls the paragraph alignment, for text it controls the text paragraph alignment.	"left"
spacing	object	✗	Custom spacing override (before / after in pt).	From defaults.spacing.code

Spacing Defaults (defaults.spacing.code)

You can configure global spacing for code elements via defaults.spacing.before.code and defaults.spacing.after.code. For example:

{
  "defaults": {
    "spacing": {
      "before": {
        "code": 10
      },
      "after": {
        "code": 12
      }
    }
  }
}

Example 1: Code rendered as plain text (no image)

This example shows how to render a JavaScript code block as plain text inside a document. The code is inserted as a paragraph with a monospace font, and renderAsImage is left as false.

Plain text code JSON

{
  "document": {
    "type": "docx",
    "filename": "code-elements-text-example",
    "title": "Code Element - Text Example"
  },
  "defaults": {
    "fontFamily": "Arial",
    "fontSize": 11,
    "spacing": {
      "before": {
        "code": 10
      },
      "after": {
        "code": 12
      }
    }
  },
  "sections": [
    {
      "type": "flow",
      "content": [
        {
          "type": "h1",
          "text": "Code Element (Plain Text)"
        },
        {
          "type": "text",
          "text": "This example shows a JavaScript function rendered as plain text (no image)."
        },
        {
          "type": "code",
          "code": "function greet(name)\n{\n  console.log(`Hello, ${name}!`);\n}\n\ngreet('Json2doc');",
          "language": "javascript",
          "renderAsImage": false,
          "align": "left",
          "spacing": {
            "before": 10,
            "after": 12
          }
        }
      ]
    }
  ]
}

In DOCX, the code is rendered using a monospace font (e.g. Consolas), preserving line breaks and indentation, but without syntax-highlighted coloring.

Example 2: Multiple code blocks rendered as images

This example shows a document that uses several code elements rendered as PNG images. Each block demonstrates different languages and options (language, backgroundColor, width, align).

Code as images JSON

{
  "document": {
    "type": "docx",
    "filename": "code-elements-image-example",
    "title": "Code Element - Image Examples"
  },
  "sections": [
    {
      "type": "flow",
      "content": [
        {
          "type": "h1",
          "text": "Code Elements Rendered as Images"
        },
        {
          "type": "text",
          "text": "The following examples show code blocks rendered via the internal Render API as PNG images with syntax highlighting."
        },
        {
          "type": "h2",
          "text": "1. Python function (centered, dark background)"
        },
        {
          "type": "code",
          "code": "def calculate_total(values):\n    total = 0\n    for value in values:\n        total += value\n    return total\n\nprint(calculate_total([1, 2, 3, 4]))",
          "language": "python",
          "renderAsImage": true,
          "backgroundColor": "#1E293B",
          "width": 700,
          "align": "center",
          "spacing": {
            "before": 12,
            "after": 16
          }
        },
        {
          "type": "h2",
          "text": "2. JSON configuration (right aligned, light background)"
        },
        {
          "type": "code",
          "code": "{\n  \"name\": \"Json2doc\",\n  \"version\": \"1.0.0\",\n  \"features\": [\n    \"pdf\",\n    \"docx\",\n    \"render-api\"\n  ]\n}",
          "language": "json",
          "renderAsImage": true,
          "backgroundColor": "#C4C4C4",
          "width": 500,
          "align": "right",
          "spacing": {
            "before": 12,
            "after": 10
          }
        },
        {
          "type": "h2",
          "text": "3. SQL query (image with auto-detected language)"
        },
        {
          "type": "code",
          "code": "SELECT id, name, created_at\nFROM users\nWHERE created_at >= '2024-01-01'\nORDER BY created_at DESC;",
          "renderAsImage": true,
          "align": "left",
          "spacing": {
            "before": 10,
            "after": 10
          }
        }
      ]
    }
  ]
}

When renderAsImage is true, json2doc renders the code into an image (respecting any language, backgroundColor and width settings) and inserts it into the document like a regular image. The final image width is always clamped to the available page width (page width minus margins and a small inner padding) so it never overflows the text area.