Werkzeugreferenz

get_app_versionInDesign® versionnur lesend

Return the version string of the running InDesign application. Use it as a sign of life before anything else. Fails with app_not_available when InDesign is not running or not ready yet. Read-only.

Keine Parameter.

list_documentsList open documentsnur lesend

List every open document, not just the frontmost one. Returns document_id (stable for this session), name, saved, path (empty when never saved), page_count, is_active and managed_story_count (stories linked to an editorial workflow such as InCopy; null when unreadable). Read-only. Note: saved true is no reliable sign that there is nothing to save.

Keine Parameter.

open_documentOpen a document

Open an existing .indd, .indt or .idml file. Returns document_id, name, page_count, facing_pages (Doppelseiten) already_open, which is true when the file was open already – it is never opened twice – and managed_story_count (stories linked to an editorial workflow such as InCopy). Because InDesign dialogs are suppressed, missing links (fehlende Verknuepfungen), out of date links and missing fonts (fehlende Schriften) come back as warnings; that is the only signal you get.

close_documentClose a document

Close a document. save_changes is required and has no default, because InDesign save dialogs are suppressed. Pass path to save under a new name; it is required for a document that has never been saved when save_changes is "yes". Returns saved_to, had_unsaved_changes and the remaining document ids. Note: merely opening a document can already set had_unsaved_changes true.

create_documentCreate a document

Create a new document. Page size from preset (A4, Letter, Legal, Tabloid) or width_mm/height_mm, orientation portrait or landscape, pages (default 1), facing_pages (Doppelseiten, default true). margins_mm is required: { top, bottom, left, right } or { top, bottom, inside, outside } – for facing pages InDesign treats left as the inside margin (Bundsteg) and right as the outside margin. columns { count, gutter_mm } sets the column guides (Spaltenhilfslinien). Returns document_id and page_ids plus the page size InDesign actually set. The document is untitled until save_document. Note: if this call times out, the document may still have been created – check list_documents before repeating.

save_documentSave a document

Save the document. With path it is a save-as (Speichern unter); without path the document is saved in place. A document that has never been saved needs path, otherwise the call fails with io_error. Returns path as InDesign reports it afterwards. A document with managed stories (editorial workflow, see list_stories lock_state) is saved with a warning: saving the layout does not save or check in those stories in the editorial system.

save_document_asSave a copy or switch file

Write the document to another file: mode copy (default) saves a copy (Kopie speichern) and the open document keeps its own file – the way to start the next issue from the current one; mode switch saves under the new name and the open document continues there (Speichern unter). template true writes an .indt. An existing file needs overwrite true. Returns path, bytes, overwritten, name and document_path of the open document afterwards. save_document is for saving in place. With managed stories (editorial workflow) both modes warn: the new file links to the same story files but is not bound to the editorial workflow.

export_pdfExport as PDF

Export the document (or a page_range) as PDF to path (the target file path – not output_path). Preset chain: preset (without it the localized built-in "High Quality Print" preset); when the result exceeds fallback_over_bytes it is exported again with fallback_preset (without both there is no second pass); a preset that does not exist falls back to the localized "High Quality Print" preset, then to the current export preferences, each with a warning. A spread preset turns single pages into spreads – check exported_page_count. The server configuration can hold default values for the three preset parameters; a parameter in the call always wins. page_range uses the printed page names as shown in InDesign ("6-8", "1, 3-5"; "+3" is the third page regardless of its name). Returns path, exported_page_count and document_page_count (page_count equals exported_page_count), bytes, preset_used and page_range_used. Pass fallback_over_bytes 0 or fallback_preset "" to disable the second pass. use_document_bleed true exports with the document bleed (Anschnitt, see set_document_bleed) for this call only, without changing the preset – needed for print-on-demand and any bleeding image, because built-in presets such as [PDF/X-1a:2001] export without bleed; false exports without bleed; omitted = as the preset says. Also returned: document_bleed_used (true/false, null if unknown) and document_bleed_mm {top, bottom, inside_or_left, outside_or_right}. InDesign writes anywhere on the machine, also outside shared folders. Can take minutes on a full issue. For an e-book use export_epub.

export_page_imageExport pages as images

Export document pages as PNG or JPEG images, one file per page (for proofs, correction mails, the website or a measuring run without PDF). Select pages with page_ids (from list_pages) or page_range like export_pdf ("6-8", "1, 3-5", "+2"; printed page names). path is the target file; with several pages the page name is inserted before the extension (Seite.png → Seite_8.png). format png (default) or jpeg, dpi 36–600 (default 150), quality low/medium/high (default)/maximum, color_space rgb (default), gray or cmyk (jpeg only), transparent_background (png), use_bleed (include the bleed), anti_alias (default true). Master pages cannot be exported. The export preferences are set for this call only and restored. Returns format, dpi, count and files[] {page_id, page_name, path, bytes}. Read the files with an image tool of the client to check a layout visually. A timed-out call may still have written files – check the folder before repeating. For an e-book use export_epub.

document_text_defaultsDocument text defaults

Read or set the document's text defaults (Textvorgaben) – the font, style, size and paragraph style every new text frame inherits and that set_text writes as local formatting. Without parameters it is read-only. Each setter works on its own; a failing one lands in problems[] without aborting the others. font takes a family name as InDesign shows it or "Family\tStyle" with a tab; font_style the style name ("Bold"); point_size 0–1296; paragraph_style the style name (not style_name). Returns the values after the change: font, font_style, point_size, paragraph_style, character_style, changed_fields[] and problems[].

set_document_setupChange document setup

Change the document setup (Dokument einrichten) of an existing document: page size via preset (A4, Letter, Legal, Tabloid) or width_mm/height_mm, orientation (swaps width and height), facing_pages, pages (page count – a lower count deletes the last pages with their contents and needs allow_page_removal true), start_page_number. At least one parameter. Margins and bleed are set with set_layout_grid and set_document_bleed. Objects are not adjusted to a new page size – unless InDesign's own layout adjustment is active (Adjust Layout, or a liquid layout rule such as scale on a page or parent page): then InDesign moves or stretches them. adjust_layout false switches both off for this call only (rules and setting are restored afterwards), so objects keep their size; true switches Adjust Layout on for this call; omitted leaves InDesign's settings as they are and warns when a page size change met an active adjustment. To widen the inside margin (Bundsteg) without stretching frames use set_layout_grid with move_objects. Returns setup (read back), previous, pages_added, pages_removed, changed and layout_adjustment {requested, active_before[], layout_rules_suspended}; warns when the page size or facing pages changed.

set_document_bleedSet bleed and slug

Set the document bleed (Anschnitt) and slug (Infobereich). bleed_mm and slug_mm each take a number (0–50, all edges) or an object with top/left/bottom/right; edges you leave out keep their value. Returns bleed_mm and slug_mm per edge plus bleed_uniform and slug_uniform. Independent of the bleed setting inside a PDF export preset. Read the current values with get_layout_grid.

list_pagesList pagesnur lesend

List the document pages. Per page: page_id, index (0-based), side (LEFT_HAND, RIGHT_HAND or SINGLE_SIDED), parent (the applied master page, "[None]" when there is none) and name, which is the printed page number. Read-only. Master pages themselves are listed by list_parent_pages.

get_page_stateSnapshot of one pagenur lesend

Snapshot of one page: page_bounds_mm and every object on it with id, type (text, image, rectangle, ellipse, polygon, line, group, other), bounds_mm, paragraph_style when the whole frame uses one, a text_snippet of up to 200 characters, child_count, parent_group_id and layer_name (Ebene). Nothing is skipped silently; unknown kinds come back as "other". Works for master pages too – take the page_id from list_parent_pages, the answer then carries is_parent_page true. All coordinates are millimetres from the top left corner of that page. Read-only. Careful: an object bleeding over the edge to the neighbouring page can show up with x = 210 instead of 0 – do not judge by coordinates alone, measure in the exported PDF. Returns coordinate_space "page": every bounds_mm is relative to the top left corner of this page and can be passed back to set_frame_bounds together with page_id.

add_pageAdd a page

Add a page at "start", at "end" (default) or relative to a page: { after_page_id } or { before_page_id } – not position or at_index. Returns page_id, index, name and spread_page_count of the spread (Druckbogen) the page landed on, with a warning when that spread now has more than two pages (with "allow pages to shuffle" off InDesign appends to the existing spread). New pages do not inherit a master page – call apply_parent_to_page. The layout window keeps its view (keep_view, default true); pass keep_view false to let InDesign show the new page.

delete_pageDelete a page

Delete a page. There is no undo. Master page objects and empty frames do not block (they are reported and go with the page); frames with text or images and threaded frames (verkettete Rahmen) block – the call then fails with invalid_state and lists them, and only force true deletes anyway. The only page of a document and master pages are always protected. Objects on the pasteboard (Montagefläche) belong to the spread, not to the page: when the spread goes with the page (the page is the only one of its spread), its pasteboard objects are listed before anything happens. When InDesign regroups the spreads (facing pages with "allow pages to shuffle"), pasteboard objects stay but can end up beside other pages. on_pasteboard_items decides: "warn" (default) deletes them with the page and warns, "abort" fails with invalid_state and details.code "pasteboard_items_present" (nothing deleted), "move" first moves them to the pasteboard of the spread of pasteboard_target_page_id (same position beside the pages; right stays right). Returns page_id, name, former_index, items_deleted, boilerplate_ignored and item_summary[]; also on_pasteboard_items, pasteboard_items[] {frame_id, type, spread_index, bounds_mm (spread coordinates), link_name, link_path, text_snippet}, pasteboard_moved_ids[], pasteboard_lost_ids[] (checked after deleting; a warning names every loss) and pasteboard_relocated[] {frame_id, spread_page_ids_before, spread_page_ids, spread_page_names_before (names before deleting), spread_page_names, spread_index, bounds_mm_before, bounds_mm, on_pasteboard} for pasteboard objects that now lie beside other pages or elsewhere (a warning names them); changes.removed_page_ids. Read list_pages again afterwards.

list_parent_pagesList master pagesnur lesend

List the master spreads (Musterseiten): name ("A-Cover"), prefix, base_name, applied_to_page_ids[] and pages[] with page_id, index, side and item_count. Those page_ids make master pages readable and editable with get_page_state, set_text or find_replace (scope frame). Read-only.

create_parent_pageCreate a master page

Create a master spread (Musterseite) with base_name (1–60 characters) and name_prefix (one capital letter; InDesign picks the next free one when omitted). facing defaults to the document's facing-pages setting. page_count (1–10) sets the number of pages of the master spread directly – also in a single-sided document, where facing true alone still gives one page. based_on names an existing master (full name with prefix) the new one is based on (Musterseite basiert auf); "[None]" for none. Returns name, page_ids[], page_count and based_on ("[None]" when none). InDesign switches the layout window to the new master spread when it is created; keep_view (default true) puts the previous page and zoom back afterwards (view_restored) – pass keep_view false to stay on the master.

apply_parent_to_pageApply a master page

Apply the master spread parent_name (full name with prefix, e.g. "A-Footer") to page_id. "[None]", "none" or "Ohne" detaches the page from its master – an ad page loses header, footer line and page number in one step. Returns page_id and parent_applied as InDesign reports it afterwards.

insert_page_number_markerInsert page number marker

Insert the automatic page number placeholder (Seitenzahl-Platzhalter) into text frame frame_id at position "start" or "end" (default end). Works on master page frames too. Returns frame_id and position.

list_sectionsList sectionsnur lesend

List the sections (Abschnitte) of the document that control page numbering: sections[] {section_id, name, start_page_id, start_page_name, start_page_index, length, continue_numbering, page_number_start, page_number_style (arabic, upper_roman, lower_roman, upper_letters, lower_letters, or a custom list name), section_prefix, include_section_prefix, marker}, count, and pages[] {page_id, name} with the page names as they result. Read-only. Every document has a section on its first page.

set_sectionStart or change a section

Start a section on page_id or change the one starting there: page_number_start (sets continue_numbering false), continue_numbering, page_number_style (arabic, upper_roman, lower_roman, upper_letters, lower_letters), section_prefix (up to 8 characters), include_section_prefix, marker (text for the section marker), name. remove true deletes the section starting on page_id (never the first). Returns created, section (read back), previous, sections[] and pages[] {page_id, name} – page names change with the numbering, so re-read them before using page names in export_pdf ranges. Use it for an issue that starts at page 3, roman front matter, or a supplement with its own numbering.

get_layout_gridLayout grid (Satzspiegel)nur lesend

Read the type area (Satzspiegel) of every document page and, by default, every master page, plus document-wide values. Per page: page_id, name, spread_index, spread_page_count, spread_position, page_offset_in_spread_mm, parent, margins_mm (top, bottom, left, right; for facing pages also inside = left and outside = right – InDesign stores the inside margin (Bundsteg) as "left"), column_count, column_gutter_mm, type_area_mm {x, y, width, height} measured from the top left corner of that page, column_width_mm, columns_positions_mm (from the left edge of the type area; a two-column grid with 5 mm gutter on 170 mm reads [0, 82.5, 87.5, 170]) and custom_column_positions. Document-wide: distinct_grids[] {margins_mm, columns, gutter_mm, page_ids}, is_uniform, baseline_grid {start_mm, increment_mm, increment_pt, relative_to (top_of_page, top_of_margin or unknown), relative_to_raw, shown, view_threshold}, baseline_grid_check {first_line_mm, starts_at_type_area_top, lines_in_type_area, last_line_mm, remainder_below_mm} for the first document page, bleed_mm {top, left, bottom, right, uniform} and slug_mm. Warnings: bleed 0, baseline grid does not fit the type area, relative_to unknown. Read-only.

set_layout_gridSet margins and columns

Set margins, column count and gutter on document pages and, by default, master pages, and redistribute the column guides evenly (relative to the type area). Whatever is omitted stays as it is. margins_mm takes top, left, bottom, right in mm – for facing pages "left" is the inside margin (Bundsteg) and "right" the outside margin. column_count 1–30, column_gutter_mm. page_ids[] limits the change to those pages (document or master pages); without it every page and the document defaults for new pages are changed – a client may block one call over all pages, so pass page_ids in blocks if needed. Optional baseline_grid {start_mm, increment_pt, relative_to: top_of_page | top_of_margin} sets the document baseline grid (Grundlinienraster). Moves only guides, never frames – unless move_objects is true: then every object on the changed pages keeps its size and moves with the inside (Bundsteg) and top margin (on a left-hand page of facing pages to the left when the inside margin grows), e.g. to widen the gutter for binding without stretching the type; locked objects, objects on locked layers and objects reaching beyond the page edge (bleeding images) stay and are listed in skipped_objects[] {item_id, page_id, reason}, moved ones in moved_objects[] {item_id, page_id, dx_mm, dy_mm}; changing the outside margin alone moves nothing. Returns changed_pages[] {page_id, name, margins_mm, column_count, column_gutter_mm, type_area_mm, column_width_mm, columns_positions_mm} read back from InDesign, with a warning per page whose column positions do not lie on the even grid. A timed-out call may still have completed in InDesign – check with get_layout_grid before repeating.

create_text_frameCreate a text frame

Create an empty text frame on page_id (document or master page) at bounds_mm {x, y, width, height}; x/y may be negative for bleed. initial_text is put in as one paragraph – "\n" becomes a forced line break, not a new paragraph; for real paragraphs create the frame empty and use set_text. The frame inherits the document text defaults, vertical justification and text wrap (Textumfluss): with wrap on, text frames underneath can be pushed into overset – pass text_wrap "none" to switch it off at creation, and vertical_justification "top" to pin the text to the top. Frame options (Textrahmenoptionen): first_baseline_offset sets the first baseline (Versatz erste Grundlinie: ascent, cap_height, leading, x_height, fixed, embox_top) with min_first_baseline_pt as the minimum in points; ignore_text_wrap true lets this frame ignore wrap of other objects (e.g. a caption over a picture with wrap); inset_mm sets the inset (Innenabstand) as one number or {top, left, bottom, right}. A one-line caption in a frame of exactly one grid line needs first_baseline_offset appropriate to the style (ascent or fixed) – otherwise it goes into overset. Returns frame_id, bounds_mm (read back, relative to the page it landed on), landed_on_page_id and landed_on_page_name (empty = pasteboard), and the frame options read back; a landing on another page is a warning, never a silent success. A timed-out call may still have created the frame – check get_page_state before repeating. Placeholders in the text become InDesign special characters (placeholders true, default): {{line_break}} (forced line break within the paragraph), {{nbsp}} (no-break space U+00A0), {{nbsp_fixed}} (fixed-width no-break space U+202F), {{thin_space}}, {{hair_space}}, {{soft_hyphen}} (discretionary hyphen), {{nb_hyphen}} (no-break hyphen), {{en_dash}}, {{em_dash}}, {{tab}}, {{column_break}}, {{frame_break}}, {{page_break}}. Unknown {{…}} stay as written with a warning; each placeholder is exactly one character in the story. Returns placeholders_replaced {name: count} and placeholders_unknown[].

create_image_frameCreate an image frame

Create an empty graphic frame (Bildrahmen) on page_id at bounds_mm; x/y may be negative for bleed. By default fill and stroke are set to [None] and the stroke weight to 0 pt, so nothing prints around the picture (appearance_cleared true); keep_default_appearance true keeps the document defaults. The frame is set to fit a picture proportionally when place_image fills it later. Returns frame_id, bounds_mm, appearance_cleared, landed_on_page_id and landed_on_page_name; a landing on another page is a warning. If a 1 pt stroke still shows in an export, run set_frame_appearance with stroke_weight_pt 0. A timed-out call may still have created the frame – check get_page_state before repeating.

create_rectangleCreate a rectangle

Create a rectangle on page_id at bounds_mm (x/y may be negative) with optional fill_hex, stroke_hex, stroke_weight_pt (points), corner_radius_mm and corner_type, fill_tint_percent, stroke_tint_percent, gradient_fill_angle_deg, gradient_stroke_angle_deg, layer_name and name. Hex colours become RGB swatches named after the value ("#1A2B3C"), reused when they exist; their ids come back as swatch_ids. For print use the existing document swatches (CMYK) instead: fill_swatch_name / stroke_swatch_name take the exact name of an existing colour, tint or gradient swatch (see list_swatches); each excludes the corresponding hex parameter. Without fill_hex the fill is [None]; without stroke_hex and stroke_weight_pt the stroke is [None] with 0 pt. The rectangle inherits the document text wrap (Textumfluss) – pass text_wrap "none" to switch it off. Returns frame_id, page_id, swatch_ids, bounds_mm, fill_color, fill_kind (none, color, tint, gradient, mixed_ink), stroke_color, stroke_kind, tints, gradient angles, corner_type, corners, layer_name, landed_on_page_id and landed_on_page_name. A timed-out call may still have created the rectangle – check get_page_state before repeating.

delete_frameDelete an object

Delete a text frame, image frame, rectangle, line or group (as a whole) by frame_id. A threaded text frame (verketteter Rahmen) takes its own text portion with it; the rest of the story stays in the other frames. There is no undo. Returns frame_id, type, was_threaded, characters_removed and removed_frame_ids (group members included). characters_removed counts only the text portion taken out of a threaded chain; it is 0 for an unthreaded frame, whose story is deleted together with the frame. A frame holding a managed story (editorial workflow, also when locked) is deleted anyway, with a warning; the story file on disk stays.

get_frame_optionsOptions of a framenur lesend

Read the options of an object as InDesign holds them: type (text, image, rectangle, ellipse, polygon, line, group, other), page_id/page_name (landing), bounds_mm, rotation_deg, text_wrap {mode, offset_mm}, appearance {fill_color, fill_kind, stroke_color, stroke_kind, stroke_weight_pt, fill_tint_percent, stroke_tint_percent, gradient_fill_angle_deg, gradient_stroke_angle_deg, gradient_fill_start_mm, gradient_fill_length_mm}, corners {top_left {type, radius_mm}, …, uniform} (null for lines and groups), effects {opacity_percent, blend_mode, drop_shadow, feather} of the object and has_effects {fill, stroke, text} (true where something deviates from normal / 100 %), parent_group_id, layer {layer_id, layer_name, visible, locked}, locked (Objekt > Sperren) and anchored {story_id, index, position} (null when the object is not anchored in text). For a text frame additionally text: columns {count, gutter_mm, type, fixed_width_mm}, inset_mm, vertical_justification, vertical_threshold_mm, first_baseline_offset (ascent, cap_height, leading, x_height, fixed, embox_top), min_first_baseline_pt, ignore_text_wrap, optical_margin_alignment and optical_margin_size_pt (story-wide, see set_story_options), threading {story_id, story_length, frame_index, frame_count, previous_frame_id, next_frame_id, overset, story_overset}, first_baseline_mm (baseline of the first line in mm from the top of the page – the direct check whether the first line sits on the baseline grid, if the layout uses one) and character_count. Read-only. Use it to copy the settings of an existing frame before rebuilding it with create_text_frame, set_frame_columns, set_frame_inset and set_text_wrap. Returns coordinate_space ("page" when the object lies on a page, "spread" on the pasteboard): bounds_mm is relative to page_id and can be passed back to set_frame_bounds together with page_id.

set_frame_boundsMove or resize an object

Move or resize an existing text frame, image frame, rectangle or line without rebuilding it: bounds_mm {x, y, width, height}. With page_id the values are relative to that page (x/y may be negative for bleed); without page_id they are spread coordinates (Druckbogen). Never changes the spread. Groups are refused (their graphics would stay behind). A rotated object takes the values in its rotated space. Resizing an image frame crops: the picture keeps its position and scale inside the frame, so a smaller frame shows less of it (the way to trim a bleed picture to the trim edge, or to crop a photo without rescaling) – use fit_frame when the picture should follow the new frame instead. Returns frame_id, bounds_mm as InDesign reports them, landed_on_page_id and landed_on_page_name; a landing on another page is a warning. Returns coordinate_space ("page" with page_id, otherwise "spread"); a page change without page_id is a warning, because page-relative values read elsewhere shift the object by one page width when passed as spread coordinates. When the object carries a text wrap, the document is recomposed afterwards and recomposed, overset_stories_before, overset_stories_after and overset_changed report whether the overset state of the document changed.

set_frame_appearanceFill and stroke of an object

Set fill, stroke colour and stroke weight of an object. fill and stroke take "#RRGGBB" (an RGB swatch is created or reused) or "none"; fill_swatch_name and stroke_swatch_name take the exact name of an existing colour, tint or gradient swatch instead (print: the document's CMYK swatches, see list_swatches) and each excludes the corresponding hex parameter. stroke_weight_pt is in points (0 or more). fill_tint_percent / stroke_tint_percent set the tint (0–100), gradient_fill_angle_deg / gradient_stroke_angle_deg the angle of a linear gradient (a warning when the swatch is no gradient). At least one parameter besides frame_id is required. Returns fill_kind and stroke_kind (none, color, tint, gradient, mixed_ink), the tints (null when none is set), the gradient angles and gradient_fill_start_mm / gradient_fill_length_mm as InDesign holds them. stroke "none" also sets the weight to 0, because [None] alone can resolve to black in localised documents – the reliable way to remove a stroke is stroke_weight_pt 0; check the export. Returns applied_fill, applied_stroke and applied_stroke_weight_pt read back from the object, plus swatch_ids of new swatches.

set_frame_columnsColumns inside a text frame

Set the number of columns inside a text frame (not the page grid): count (1 or more; the parameter is count, not column_count) and gutter_mm (Spaltenabstand; without it the frame keeps its current gutter – InDesign's own default for new frames is 1 pica = 4.233 mm). Returns frame_id, count and gutter_mm read back. Fails with invalid_state for anything but a text frame.

set_frame_insetInset of a text frame

Set the inset spacing (Innenabstand) of a text frame: inset_mm {top, left, bottom, right}, all four required, 0 or more; and/or the vertical justification (vertikale Ausrichtung, Textrahmenoptionen): vertical_justification top, center, bottom or justify. At least one of the two; what is omitted stays. Returns frame_id, inset_mm and vertical_justification read back (get_frame_options reads both under text).

set_text_wrapText wrap of an object

Set the text wrap (Textumfluss) of an object: mode none, bounding_box, object_shape, jump_object or next_column, with an optional offset as offset_mm or offset_pt {top, left, bottom, right} (one of them, not both; object_shape uses only one distance). The reliable cure for text frames pushed into overset by a new frame is mode "none". Returns frame_id, mode and offset_mm read back. The document is recomposed afterwards; recomposed, overset_stories_before, overset_stories_after and overset_changed report whether the overset state of the document changed.

thread_text_framesThread two text frames

Thread (verketten) two text frames into one story: the text of source_frame_id continues in target_frame_id. Already threaded to each other = no-op (already_threaded true). Text already in the target is merged into the story after the source text (warning). A source that already continues elsewhere, or a target that already continues another frame, is refused with invalid_state. Returns source_frame_id, target_frame_id, story_id and story_character_count.

fit_frameFit frame or content

InDesign's fitting commands (Anpassen) as one call. For a graphic frame: content_to_frame (distorts), fit_proportionally (whole picture visible, may leave space), fill_proportionally (frame filled, picture cropped), center_content, or frame_to_content (the frame takes the size of the picture, top left corner stays). For a text frame only frame_to_content: the frame shrinks or grows to its text (Rahmen an Inhalt anpassen) – InDesign fits width and height (the width to the longest line); keep_width true fits the height only and keeps the width (via auto-size height only, reference top left) – the usual choice for headlines and captions; if the layout uses a baseline grid, check the result against it. Returns frame_bounds_before_mm, frame_bounds_mm, frame_changed, and for pictures graphic_bounds_mm, fits_frame and effective_ppi (warning below min_ppi), for text overset. Fails on groups, lines, empty graphic frames and members of a group. Returns coordinate_space ("page", or "spread" on the pasteboard); when the object carries a text wrap the document is recomposed afterwards (recomposed, overset_stories_before, overset_stories_after, overset_changed).

anchor_frame_in_textAnchor object in text

Anchor a frame, picture, line or group at a text position (verankertes Objekt) so it moves with the text on reflow: target_frame_id names a frame of the story, index the character position (default: end of the story), position inline (on the baseline), above_line, or custom with offset_mm {x, y}, anchor_point, horizontal_reference (anchor_location, column_edge, text_frame, page_margins, page_edge), vertical_reference (line_baseline, line_xheight, line_ascent, cap_height, top_of_leading, embox_top, embox_middle, embox_bottom, column_edge, text_frame, page_margins, page_edge), horizontal_alignment (left, center, right, text), vertical_alignment (top, center, bottom), keep_within_frame, lock_position. For above_line, horizontal_alignment (left, center, right, text) aligns the object in the text column and space_before_mm/space_after_mm set the space before and after it (Abstand davor/danach). The object leaves its page and becomes part of the story (an U+FFFC character at index). Returns frame_id (read back; a new id is warned), story_id, index, story_length, settings (for above_line with space_before_mm, space_after_mm), bounds_mm, page_id (the page the anchored object stands on after the story is recomposed) and story_overset (warning). Fails on group members, already anchored objects, a frame of the target story, locked layers. An anchored object leaves its place on the page and follows the text on reflow – anchor deliberately (captions, marginalia, inline symbols) and leave objects that must keep their position unanchored.

place_imagePlace an image or PDF

Place an image or PDF file (real path on the InDesign machine) into a graphic frame, replacing whatever it held (crop and scale are reset). fit: fill_proportionally, fit_proportionally, fit_content_to_frame or center_content; without it the frame fitting options of the frame apply. pdf_crop chooses the PDF page box: media (InDesign default – the whole sheet including printer marks, the usual reason for misplaced ads), crop, trim, bleed (for bleed ads), art or content; pdf_page picks the page (default 1). When the PDF has no such box (a QR code PDF without TrimBox, say), InDesign refuses – the tool then falls back to the next larger box (bleed → trim → crop → media) with a warning and reports pdf_crop_used; without pdf_crop the box preset in InDesign applies (the last choice of the place dialog, not always media) and the same fallback starts from that box; pdf_crop_fallback false turns that off and returns the io_error instead. The place preferences are set for this call only and restored. Returns frame_id, link_status, frame_bounds_mm, graphic_bounds_mm, pdf_crop_used and fits_frame (true when the graphic covers the frame within 0.2 mm; otherwise a warning); a warning when the effective resolution is below min_ppi. A changed CropBox of a PDF is ignored by InDesign; for asymmetric bleed derive a placement copy of the PDF. A timed-out call may still have placed – check get_page_state before repeating.

position_image_in_framePosition a placed graphic

Move the graphic inside a frame without scaling it; the frame stays as it is (frame bounds, crop edges and page). align puts the graphic's reference point onto the same reference point of the frame (center, top, bottom, left, right, top_left, top_right, bottom_left, bottom_right – e.g. top_left: upper left corners meet, center: centred); offset_mm {x, y} then shifts it by x/y mm (positive = right/down). Pass align, offset_mm or both. Returns frame_id, graphic_id, align, offset_mm, moved_by_mm {x, y}, graphic_bounds_mm, graphic_bounds_before_mm and frame_bounds_mm (relative to page_id, coordinate_space "page"; "spread" on the pasteboard) and fits_frame – a warning when the graphic no longer covers the frame. To change the size use fit_frame.

list_linksList linksnur lesend

List the links (Verknuepfungen) of the document, optionally filtered by path_contains (substring of path or file name, case-insensitive). Per link: link_id, file_name, file_path, status (NORMAL, LINK_MISSING, LINK_OUT_OF_DATE, EMBEDDED), page_id, page_name and frame_id (for a linked story file such as an InCopy story: its first text frame and the page of that frame). Also count. Where the holding object lies: container_id (the frame or object that holds the graphic, also when it lies on no page; for a linked story file its first text frame), container_type, graphic_type (InDesign class of the linked object, e.g. Image, PDF, EPS, Story), location (page, parent_page, pasteboard, anchored – in a story, then with story_id and in_overset true when the anchor sits in overset text –, or unknown), spread_id (the spread or parent spread of the object; for anchored objects the spread of the text frame, null in overset). For an object anchored in overset text InDesign still reports a page_id (the page it would follow) – in_overset true is the reliable sign. A link with page_id null and location pasteboard or anchored with in_overset true is a leftover that does not print. Use it to match pictures to articles by page number or to spot motifs of old issues by file name. Read-only.

update_linksUpdate out-of-date links

Update links whose file changed on disk ("Verknuepfung aktualisieren"): link_ids[] (1 to 500) or, without it, every LINK_OUT_OF_DATE link. Ids that are not out of date come back as "nothing to do", no error. Returns results[] {link_id, name, page_name, status_before, status_after}, updated, failed and considered.

get_frame_textRead the text of a framenur lesend

Read the story of a text frame: story_id, story_length, paragraphs[] {index, start_index, end_index (exclusive, without the break), end_index_incl_break, paragraph_style, text, is_empty, break_type (paragraph, column, frame, page, odd_page, even_page or none for the last paragraph)} and overset for this frame. Column breaks count like paragraph marks; zero-width characters (U+FEFF) are returned as they are. For a threaded frame the whole story is returned, with frame_start_index and frame_end_index marking this frame's portion – pass only_frame_portion true to get only the paragraphs in this frame (text clipped at the frame boundaries, clipped_start/clipped_end mark the cut), and max_chars to cap the text returned (truncated true, paragraphs_omitted counts the rest). Indices always refer to the whole story, so they can be used with set_text_in_range and the *_to_range tools. Also lock_state of the story (none, unmanaged_story, checked_in_story, checked_out_story, locked_story, embedded_story, missing_lock_state, mixed_lock_state; null when unreadable) and managed_file (path of the editorial file for a managed story, home folder as ~; otherwise null) – writing tools refuse checked_in_story, locked_story, missing_lock_state and mixed_lock_state. Read-only. There is no include_overset parameter.

set_textReplace the text of a frame

Replace the whole story of a text frame (really replace, never append): text with real line breaks as paragraph marks ("\n" or "\r\n" in the parameter become paragraph returns; U+2028 stays a forced line break). "" empties the frame. The text takes the document text defaults as local formatting – apply a paragraph style afterwards with apply_paragraph_style_to_range over the whole story. For a threaded frame the entire story across all frames is replaced (warning). Returns frame_id, character_count read back and overset. Stories managed by an editorial workflow (InCopy) that are not checked out here (lock_state checked_in_story, locked_story, missing_lock_state or mixed_lock_state) are refused before anything is written: invalid_state with details.code "story_locked" (details: frame_id, story_id, lock_state, managed_file) – check the story out in the editorial system or in InCopy first. Placeholders in the text become InDesign special characters (placeholders true, default): {{line_break}} (forced line break within the paragraph), {{nbsp}} (no-break space U+00A0), {{nbsp_fixed}} (fixed-width no-break space U+202F), {{thin_space}}, {{hair_space}}, {{soft_hyphen}} (discretionary hyphen), {{nb_hyphen}} (no-break hyphen), {{en_dash}}, {{em_dash}}, {{tab}}, {{column_break}}, {{frame_break}}, {{page_break}}. Unknown {{…}} stay as written with a warning; each placeholder is exactly one character in the story. Returns placeholders_replaced {name: count} and placeholders_unknown[].

set_text_in_rangeReplace a character range

Replace characters start_index (inclusive) to end_index (exclusive) of the story of a text frame with text; start == end inserts, text "" deletes the range. The new text keeps the formatting of the first replaced character up to its first paragraph mark (keep_format_of "start", default) – also when the range begins a paragraph that follows a paragraph with other formatting; every further new paragraph takes the formatting and paragraph style of the replaced paragraph at the same position (beyond the last one: of the last replaced paragraph). If the range begins with a paragraph mark, the paragraphs merge and the new text continues that paragraph in its formatting. The right way for formatted placeholders and for a full swap (0 to story_length). keep_format_of "before" leaves the choice to InDesign (the range is replaced in one step); "none" removes character style and local character formatting from the new text, so it shows its paragraph style. An insertion (start == end) takes InDesign's formatting of the insertion point unless keep_format_of is "none". An empty line is two line breaks. Indexes come from get_frame_text. Returns frame_id, replaced_chars, inserted_chars, story_length and keep_format_of. Stories managed by an editorial workflow (InCopy) that are not checked out here (lock_state checked_in_story, locked_story, missing_lock_state or mixed_lock_state) are refused before anything is written: invalid_state with details.code "story_locked" (details: frame_id, story_id, lock_state, managed_file) – check the story out in the editorial system or in InCopy first. Placeholders in the text become InDesign special characters (placeholders true, default): {{line_break}} (forced line break within the paragraph), {{nbsp}} (no-break space U+00A0), {{nbsp_fixed}} (fixed-width no-break space U+202F), {{thin_space}}, {{hair_space}}, {{soft_hyphen}} (discretionary hyphen), {{nb_hyphen}} (no-break hyphen), {{en_dash}}, {{em_dash}}, {{tab}}, {{column_break}}, {{frame_break}}, {{page_break}}. Unknown {{…}} stay as written with a warning; each placeholder is exactly one character in the story. Returns placeholders_replaced {name: count} and placeholders_unknown[].

find_replaceFind and replace text

Find and replace text in the document or in one frame: find, replace, mode literal or grep (default literal), scope document or frame (frame needs frame_id), include_master_pages, include_hidden_layers, include_locked_layers (all default false), case_sensitive and whole_word (default false). dry_run true only counts and lists up to 200 matches with frame_id, page_name and index – use it before any name replacement. GREP metacharacters: ~M column break, ~R frame break, ~P page break, ~S non-breaking space (a literal U+00A0 is not found in literal mode); a straight " in GREP matches every quote, including typographic ones. Returns replacements, matches_found, scope, mode and master_pages_included. Locked managed stories (editorial workflow, lock_state as in get_frame_text) are never changed: their matches are left out of replacements and matches_found (also in dry_run) and listed in skipped_locked[] {story_id, frame_id, lock_state, managed_file, matches}, with a warning; without include_locked_layers InDesign does not search them, and a warning says how many there are. changes.modified_frame_ids lists the frames with replacements. No undo.

place_text_filePlace a text file

Place a manuscript file (.docx, .doc, .rtf or .txt on the InDesign machine) into a text frame – the cheap way for long articles instead of passing the text as a string. mode replace (default) empties the story first; append adds at the end of the story. retain_formatting false (default) imports plain text (Word styles and local formatting removed) so that paragraph_style (applied to every placed paragraph, like apply_paragraph_style_to_range) gives the document's paragraph style; retain_formatting true keeps Word styles and local formatting and imports the Word paragraph styles (names that already exist in the document are used as they are). style_map {"Word style": "document style"} maps Word paragraph styles to existing document styles after the import (forces retain_formatting true) and removes the mapped Word styles again (styles_removed); every target style must exist. typographers_quotes (default true) converts straight quotes. page_breaks (.docx, .doc, .rtf) decides what becomes of page breaks in the Word file: none (default – they are dropped and the text runs on), page_break (InDesign page breaks, Seitenumbruch – e.g. for a front matter with title, imprint and dedication on pages of their own) or column_break; a Word break in an otherwise empty paragraph leaves that empty paragraph at the top of the next page. Footnotes and endnotes are imported, tables come in as InDesign tables, graphics, index and table of contents are not imported (build them in InDesign with create_toc and with add_index_entry plus generate_index). Returns placed_start_index, placed_end_index and inserted_chars (story indices for the *_to_range tools), story_length, paragraph_count, styles_added (paragraph styles the import created – remove or map them), styles_mapped and overset of the story. autoflow true (Sitzung 8) keeps adding pages after the page of the last frame – same parent page, a frame with the size and frame options of the last one (on facing pages placed into the type area of the new page when the last frame fills its type area, otherwise mirrored at the spine; placement type_area | mirrored | same per added frame) (columns, gutter, insets, vertical justification, first baseline – copied value by value), threaded – until the text fits or max_pages (default 20) is reached; the result carries autoflow {pages_added, frames_added[] {frame_id, page_id, bounds_mm, placement, frame_options_copied, frame_options_failed[], frame_options_skipped[] (values that do not apply, e.g. vertical_threshold without vertical justify), columns {count, gutter_mm}}, overset, stopped}. Without autoflow, thread frames with thread_text_frames; to continue the autoflow of a story already placed (overset after max_pages, later edits) use autoflow_story. Autoflow keeps the layout window where it was (keep_view, default true; view_restored in the answer) – pass keep_view false to follow the new pages. A timed-out call may still have placed – check get_frame_text before repeating. Stories managed by an editorial workflow (InCopy) that are not checked out here (lock_state checked_in_story, locked_story, missing_lock_state or mixed_lock_state) are refused before anything is written: invalid_state with details.code "story_locked" (details: frame_id, story_id, lock_state, managed_file) – check the story out in the editorial system or in InCopy first.

autoflow_storyAutoflow an existing story

Continue the autoflow of a story that is already in the document – no file needed: while the story overflows (Übersatz), add a page after the page of its last frame (same parent page) with a threaded frame of the size and frame options of the last frame, exactly as place_text_file with autoflow true does, until the text fits or max_pages (default 20, at most 2000) is reached. frame_id is any text frame of the story. A story that fits already is left as it is (pages_added [] and stopped "fits"). Returns frame_id, story_id, overset and autoflow {pages_added, frames_added[] {frame_id, page_id, bounds_mm, placement, frame_options_copied, frame_options_failed[], frame_options_skipped[], columns {count, gutter_mm}}, overset, stopped} – the same as place_text_file – and view_restored (keep_view, default true). A timed-out call may still have added pages – check list_pages before repeating. Stories managed by an editorial workflow (InCopy) that are not checked out here are refused before anything is written: invalid_state with details.code "story_locked".

list_storiesList storiesnur lesend

Overview of the stories (Textabschnitte) of the document: which frames belong to which story and in what order, and which story overflows. stories[] {story_id, frame_ids (chain order), frame_count, frames[] {frame_id, index, page_id, page_name, on_pasteboard, on_parent_page, bounds_mm}, character_count, paragraph_count, table_count, overset, on_parent_page, first_page_id, first_page_name, first_paragraph_style, snippet, lock_state, managed_file}, count, total_stories, overset_count (warning when above 0). Stories on parent pages are skipped unless include_parent_pages true; empty stories are listed unless include_empty false; page_id keeps only stories with a frame on that page. lock_state is the state of a story in an editorial workflow such as InCopy (none, unmanaged_story, checked_in_story, checked_out_story, locked_story, embedded_story, missing_lock_state, mixed_lock_state; null when unreadable); managed_file is the path of its editorial file (home folder as ~) for managed stories, otherwise null. Read-only. get_frame_text reads one story; thread_text_frames changes the chain.

get_frame_linesLines of a text frame (composition)nur lesend

Read the composed lines of a text frame directly from InDesign, per text column – the basis for widow/orphan checks (Hurenkind, Schusterjunge), hyphen ladders, empty lines and the comparison of column starts, without a PDF export. Returns frame_id, story_id, frame_index (position of the frame in the story), page_id, column_count, line_count, columns[] {column_index, bounds_mm (from frame, inset, column count and gutter), line_count, first_baseline_mm, last_baseline_mm (mm from the top of the page), starts_with_last_line_of_paragraph (widow suspicion), ends_with_first_line_of_paragraph (orphan suspicion), starts_with_empty_line, consecutive_hyphens_max, ends_with_single_word, single_word_last_lines[], lines[] {index (in the column), start_index, end_index (story indices, end exclusive – usable in the *_to_range tools), baseline_mm, ascent_pt, descent_pt, left_mm, right_mm, paragraph_index (0-based in the story), is_first_line_of_paragraph, is_last_line_of_paragraph, paragraph_line_count (story-wide, so a paragraph continuing in the next frame is still counted whole), ends_with_hyphen, is_empty, word_count, last_char, text (only with include_text)}}, overset and truncated. Pitfalls: only composed text has lines – overset text has none; an automatic hyphen is not part of the text, so ends_with_hyphen is inferred when a line ends and the next line of the same paragraph begins with a letter; the last line of a paragraph that continues in the next frame is the last visible line here, not the last line of the paragraph (compare paragraph_line_count); lines inside tables are not Line objects and are not listed. Read-only. Returns coordinate_space ("page" or "spread") for the coordinates reported.

set_story_optionsStory options (optical margin alignment)

Read or set story-wide options of the story a text frame belongs to (frame_id names any frame of the story): optical_margin_alignment (optischer Randausgleich / hängende Interpunktion – punctuation and letter edges hang slightly outside the column edge, which makes justified edges look straight) and optical_margin_size_pt (the point size the alignment is calculated for; usually the body text size, 0.1–1296). Without parameters it is read-only. Returns story_id, frame_ids[] of the story in threading order, the two values after the change, previous {…}, changed[] and overset of the story. Optical margin alignment recomposes every line of the story – check get_frame_lines afterwards. get_frame_options shows the two values under text as well.

list_text_variablesList text variablesnur lesend

List the text variables (Textvariablen) of the document: variables[] {name, type (custom_text, running_header_paragraph, running_header_character, file_name, output_date, creation_date, modification_date, last_page_number, chapter_number, or the raw type), options per type (text; paragraph_style/character_style, use first|last, text_before, text_after, delete_end_punctuation; include_extension, include_path; format), instance_count (instances in the stories)}, count. Read-only. Every document carries InDesign's default variables.

create_text_variableCreate or update a text variable

Create a text variable (Textvariable) or update the options of an existing one with the same name and type: type custom_text (text), running_header_paragraph (paragraph_style, use first|last, text_before, text_after, delete_end_punctuation), running_header_character (character_style, …), file_name (include_extension, include_path, text_before, text_after), output_date/creation_date/modification_date (date_format, text_before, text_after), last_page_number, chapter_number. remove true deletes the variable (and its instances in the text – warning). A running header from the headline style is the classic use on parent pages: create the variable, then insert_text_variable into a frame on the parent page.

insert_text_variableInsert a text variable

Insert an instance of a text variable at a text position: frame_id (a frame of the story, also on a parent page), name, index (default: end of the story). Returns instance_id, story_id, frame_id, index, result_text (what the variable shows there), story_length, overset. The instance counts as one character in the story.

list_paragraph_stylesList paragraph and character stylesnur lesend

List the paragraph styles (Absatzformate) of the document, including those in style groups: styles[] {name, style_id, group ("" at top level, "Group/Subgroup" nested), based_on, font_family, font_style, point_size, leading_pt (null when automatic), leading_auto, fill_swatch, alignment, space_before_pt, space_after_pt, hyphenation, tracking, keep_options, hyphenation_options, justification_options, drop_cap {lines, characters, character_style}} and the character styles (Zeichenformate) as character_styles[] {name, style_id, group, based_on, font_family, font_style, point_size, fill_swatch, tracking – null for attributes the style does not set}. Internal styles whose name starts with "[" are excluded (internal_styles_excluded counts them). Read-only.

define_paragraph_styleDefine a paragraph style

Create a paragraph style (Absatzformat) with name and any of font_family, font_style (exact InDesign style name, e.g. "75 Bold"), size_pt, leading_pt (points or "auto"), alignment (left, center, right, justify = Blocksatz with the last line left), color_hex (creates an RGB swatch named after the hex value) or swatch_name (an existing swatch by exact name – the way to a CMYK or spot colour; not together with color_hex), space_before_pt, space_after_pt, tracking (Laufweite in 1/1000 em), hyphenation, and the option groups keep_options (Umbruchoptionen: keep_with_next, keep_first_lines, keep_last_lines, keep_lines_together, keep_all_lines_together, keep_with_previous, start_paragraph), hyphenation_options (Silbentrennungseinstellungen) and justification_options (Blocksatz-Abstände, composer). Indents in mm: left_indent_mm, first_line_indent_mm (negative for a hanging indent, never further left than the left indent), right_indent_mm, last_line_indent_mm. tab_stops[] {position_mm, alignment left|center|right|character, leader, align_on} replaces the whole tab list ([] clears it); language selects the dictionary by the name InDesign shows, its untranslated name or an ICU locale (de_DE, en_GB – the safest form). The answer reads them back under indents {left_indent_mm, first_line_indent_mm, right_indent_mm, last_line_indent_mm, tab_stops[], language {name, untranslated_name, icu_locale}}. drop_cap {lines (0 = off), characters, character_style} sets the drop cap (Initiale); an opening quotation mark counts as a character, so characters 2 drops it together with the first letter. based_on sets the parent style (Basierend auf), also from a group ("Group/Style" for an ambiguous name); group puts a new style into a style group (Formatgruppe), path "A/B" or ["A", "B"], creating missing groups. The answer adds based_on and group as read back, created_groups[] (paths of groups created by this call) and changes.created_group_ids. InDesign names a family with a format suffix such as "Source Sans 3 (OTF)" or "(TT)" when it knows the family in more than one format; pass the family with or without that suffix – the connector matches both and reads back the name InDesign uses. Strict keep options can produce overset or empty column ends – check overset and get_frame_lines afterwards. on_collision decides what happens when the name exists: error (default), update or version ("Name 2"). The font must be installed: InDesign rejects a font it does not have, even as family plus style (not_found with available_styles) – define such styles on the machine that has the font. Returns style_id, name (differs from the request with version), collision (none, updated, versioned), existed, applied[] and the definition read back (with keep_options, hyphenation_options and justification_options as InDesign holds them).

define_character_styleDefine a character style

Create a character style (Zeichenformat) with name and at least one of font_family, font_style (exact InDesign style name), point_size, fill_hex (creates an RGB swatch) or swatch_name (an existing swatch by exact name; not together with fill_hex), and tracking (Laufweite in 1/1000 em, -1000 to 10000; where the style is applied it replaces the tracking of the paragraph style – see apply_character_style_to_range). on_collision: error (default), update or version. Returns style_id, name, collision (none, updated, versioned), existed, applied[] and the definition read back (null for attributes the style leaves untouched); based_on alone is enough for a new style. based_on sets the parent style (Basierend auf), also from a group ("Group/Style" for an ambiguous name); group puts a new style into a style group (Formatgruppe), path "A/B" or ["A", "B"], creating missing groups. The answer adds based_on and group as read back, created_groups[] (paths of groups created by this call) and changes.created_group_ids. InDesign names a family with a format suffix such as "Source Sans 3 (OTF)" or "(TT)" when it knows the family in more than one format; pass the family with or without that suffix – the connector matches both and reads back the name InDesign uses.

apply_paragraph_style_to_rangeApply a paragraph style to a range

Apply a paragraph style (Absatzformat) to every paragraph touched by the character range start_index (inclusive) to end_index (exclusive) of the story of a text frame. Clears paragraph overrides, character styles and local character formatting of those paragraphs; never changes text. Caveat: when start_index is the paragraph mark of the preceding paragraph, that paragraph is formatted too (warning) – start one character later. Recommended order: base style over the whole story first, then the special styles. One call is enough (it runs the clean-up twice internally). Returns frame_id, story_id, style_applied, affected_paragraphs, first_paragraph_start_index and last_paragraph_end_index. Stories managed by an editorial workflow (InCopy) that are not checked out here (lock_state checked_in_story, locked_story, missing_lock_state or mixed_lock_state) are refused before anything is written: invalid_state with details.code "story_locked" (details: frame_id, story_id, lock_state, managed_file) – check the story out in the editorial system or in InCopy first.

apply_character_style_to_rangeApply a character style to a range

Apply an existing character style (Zeichenformat) to the characters start_index (inclusive) to end_index (exclusive) of the story of a text frame. The style must exist (define_character_style; list_paragraph_styles lists them). Never changes text. Returns frame_id, characters_affected, style_applied and tracking {effective, character_style, paragraph_style}: a character style that carries its own tracking replaces the tracking of the paragraph style for that range (it is not added) – a paragraph style with tracking 100 plus a character style with tracking 260 gives 260, visibly wider. effective is what InDesign uses at the first character of the range; character_style is null when the style leaves tracking alone. Stories managed by an editorial workflow (InCopy) that are not checked out here (lock_state checked_in_story, locked_story, missing_lock_state or mixed_lock_state) are refused before anything is written: invalid_state with details.code "story_locked" (details: frame_id, story_id, lock_state, managed_file) – check the story out in the editorial system or in InCopy first.

apply_character_format_to_rangeFormat a range locally

Local character formatting without a style for the characters start_index (inclusive) to end_index (exclusive) of the story of a text frame: font_style (exact InDesign style name – fetch it with get_font_info_at_index first, "75 Bold" rather than "Bold"; optional font_family to switch the family), swatch_name (an existing swatch, exact name; built-ins are "Black", "Paper", "None"), superscript (true/false), tracking (Laufweite in 1/1000 em, -1000 to 10000; the server configuration can set a tolerance beyond which a warning is given), point_size (0–1296, the only way to a size without a paragraph style). At least one attribute. Never changes text. Returns applied[], point_size_applied, font_family, font_style and fill_color read back at the first character for a cross-check, plus characters_affected. Stories managed by an editorial workflow (InCopy) that are not checked out here (lock_state checked_in_story, locked_story, missing_lock_state or mixed_lock_state) are refused before anything is written: invalid_state with details.code "story_locked" (details: frame_id, story_id, lock_state, managed_file) – check the story out in the editorial system or in InCopy first.

set_paragraph_optionsSet paragraph options (alignment, hyphenation, keep, justification)

Set paragraph options of a text frame: alignment (left, center, right, justify_left, justify_center, justify_right, justify_full), hyphenation (true/false – usually false for headlines), no_break (true/false, keeps the text of the paragraphs on one line), and the option groups keep_options (Umbruchoptionen: keep_with_next, keep_first_lines, keep_last_lines, keep_lines_together, keep_all_lines_together, keep_with_previous, start_paragraph), hyphenation_options (Silbentrennungseinstellungen: words_longer_than, after_first, before_last, ladder_limit, zone_mm, capitalized_words, last_word, across_columns, weight) and justification_options (word_spacing, letter_spacing, glyph_scaling, single_word_justification, composer, auto_leading_percent). Indents in mm: left_indent_mm, first_line_indent_mm (negative for a hanging indent, never further left than the left indent), right_indent_mm, last_line_indent_mm. tab_stops[] {position_mm, alignment left|center|right|character, leader, align_on} replaces the whole tab list ([] clears it); language selects the dictionary by the name InDesign shows, its untranslated name or an ICU locale (de_DE, en_GB – the safest form). The answer reads them back under indents {left_indent_mm, first_line_indent_mm, right_indent_mm, last_line_indent_mm, tab_stops[], language {name, untranslated_name, icu_locale}}. drop_cap {lines (0 = off), characters, character_style} sets the drop cap (Initiale); an opening quotation mark counts as a character, so characters 2 drops it together with the first letter. Without start_index/end_index every paragraph of the frame is changed; with them every paragraph the range touches. Returns paragraphs_changed, alignment, hyphenation, no_break, keep_options, hyphenation_options, justification_options, indents, drop_cap of the first paragraph read back after the change, and overset of the story – strict keep options can push text into overset or leave empty column ends; check get_frame_lines.

get_font_info_at_indexFont at a characternur lesend

Read the font at story index of a text frame: font_family, font_style (the exact style name to use in apply_character_format_to_range or define_paragraph_style), font_status (installed, substituted, not_available), available_styles[] of that family as installed, point_size, paragraph_style, character_style (localized name) and character_style_is_none. Read-only.

find_font_usageWhere is a font usednur lesend

Find where fonts are used in the document. fonts_used[] {family, style, status (installed, substituted, not_available), occurrences, characters} is always complete; occurrences[] {family, style, status, story_id, frame_ids[], page_id, page_name, is_master, start_index, end_index, snippet} is filtered by font_family and font_style (exact names, case-insensitive – "Futura" does not match "Futura PT"), only_missing (status other than installed) and include_master_pages (default true). Runs of the same family and style are merged; at most 500 occurrences are listed. Read-only.

debug_inspect_runInspect formatting at a characternur lesend

Diagnosis only: the effective formatting at story index (default 0) of a text frame – point_size, leading_pt, applied_paragraph_style, applied_character_style (InDesign's own name, localized – "[Ohne]" in German) with character_style_is_none (true when no character style is applied, the language-independent check), fill_color, applied_font, font_style, tracking, horizontal_scale, vertical_scale, style_overridden (local formatting on top of the style), frame_scale {horizontal, vertical} of the frame and paragraph {index (0-based in the story), start_index (story index of its first character), alignment, hyphenation, keep_options, hyphenation_options, justification_options} of the paragraph holding the character. With style_name also style {found, kind, matches, duplicated, nested, groups[], definition} – whether the name occurs more than once or inside a group. The only way to see local formatting hiding behind a correct style name. Read-only.

list_swatchesList swatchesnur lesend

List the swatches (Farbfelder) of the document: swatches[] {swatch_id, name, kind (none, color, tint, gradient, mixed_ink), space (RGB, CMYK, LAB, MIXED_INK), model (process, spot, registration), values (RGB 0–255 or CMYK percent; ink percentages for mixed inks), tint_percent and base_color for tints, stop_count, type (linear, radial) and stops[] {index, swatch_name, location, midpoint} for gradients, built_in}. include_built_in false hides None, Black, Paper and Registration. Read-only. Use the exact names for swatch_name parameters (create_rectangle, set_frame_appearance, apply_character_format_to_range); hex parameters create RGB swatches, which print differently from the CMYK swatches of the document.

create_swatchCreate a colour swatch

Create a process colour swatch (Farbfeld) with the exact name (1–60 characters) from hex (RGB, "#1A2B3C") or cmyk ({c, m, y, k} in percent – for print production); exactly one of the two. on_collision: error (default), update (rewrites the values of the existing colour) or version ("Name 2"). Returns name, swatch_id, collision (none, updated, versioned), existed, space (rgb or cmyk) and values.

list_toc_stylesList table of contents stylesnur lesend

List the table of contents styles (Inhaltsverzeichnisformate) of the document: toc_styles[] {name, title, title_style, include_hidden_layers, run_in, include_book_documents, create_bookmarks, entries[] {paragraph_style (the style whose paragraphs become entries), level, entry_style (paragraph style of the entry in the TOC), page_number_position after|before|none, separator, page_number_style, separator_style, sort_alphabetical}}, count, and toc_stories[] {story_id, frame_ids, page_ids, page_names, paragraph_count, length, overset} – the tables of contents already in the document. Every document carries InDesign's default style (localized name, e.g. "[Default]"). A style name shown in square brackets such as "[Same style]" means InDesign's default. Read-only.

define_toc_styleCreate or change a table of contents style

Create a table of contents style (Inhaltsverzeichnisformat) or change the one with the same name: title (heading of the TOC, "" for none), title_style, entries[] in TOC order – each {paragraph_style (paragraphs with this style become entries), level (1 = top, default 1), entry_style (paragraph style for the entry), page_number_position after (default) | before | none, separator (between entry text and page number, e.g. "^t" for a tab), page_number_style, separator_style, sort_alphabetical}. entries replaces all entries of an existing style; a new style needs entries. include_hidden_layers, run_in (lowest level on one line), create_bookmarks (PDF bookmarks). Every named style must exist (not_found; create them with define_paragraph_style / define_character_style). remove true deletes the style. Returns created, updated, removed and toc_style (as list_toc_styles). Then call create_toc.

create_tocCreate or update a table of contents

Generate a table of contents (Inhaltsverzeichnis) from a TOC style (list_toc_styles, define_toc_style) into a new text frame on page_id – at position_mm (InDesign sizes the frame up to the margins) or exactly at bounds_mm. replace true updates the existing table of contents in its frame (after text or page changes) – page numbers are not live, so run it again after every change. include_overset also lists headings in overset text. Returns story_id, frame_id, frame_ids, page_id, page_name, page_ids, page_names, bounds_mm (of the first frame, relative to its page), paragraph_count, length, overset, replaced and lines[] {text, paragraph_style} (first 500 paragraphs; lines_truncated). Plus toc_style and entry_count (non-empty paragraphs except the title; null when lines_truncated). Warnings: no entries (no paragraph uses the styles), overset (enlarge or thread the frame), a second table of contents. The view of the layout window stays (keep_view, default true). Text placed with place_text_file brings no table of contents from Word – build it here.

add_index_entryAdd an index entry

Add an index entry (Registereintrag): topic as a path of 1 to 4 levels (missing levels are created), sort_as (sort key per level). Where it points: a text range of a story (frame_id with start_index and optional end_index, indices as get_frame_text) or find_text – every occurrence in the document or, with frame_id, in that story (case_sensitive, whole_word, max_matches default 100; text of tables of contents and indexes is skipped). page_reference_type current_page (default), to_next_style_change, to_next_use_of_style (limit_paragraph_style), to_end_of_story, to_end_of_section, to_end_of_document, for_next_paragraphs or for_next_pages (limit_count), suppress_page_numbers; page_number_style overrides the character style of the page number. cross_reference {type see (default) | see_also | see_or_see_also | see_herein | see_also_herein | custom | custom_before | custom_after, topic (path, created if missing), custom_text} adds a "see" reference instead of or besides the page reference. A page reference inserts an invisible marker character before its source, so story indices behind it shift by one. Stories that are locked by an editorial workflow (lock_state) are refused (story_locked) or, with find_text, skipped (skipped_locked). Returns topic, index_created, created_topics[] (paths), page_references[] {page_reference_id, type, page_id, page_name, frame_id, story_id, index, in_overset}, page_reference_count, matches_found, skipped_locked, cross_reference. Then generate_index.

list_indexList index topicsnur lesend

List the index (Register) of the document: index_exists, topics[] in tree order {path, level, name, sort_as, page_reference_count, cross_reference_count, page_references[] {page_reference_id, type, page_id, page_name, frame_id, story_id, index, in_overset}, cross_references[] {cross_reference_id, type, topic (path), custom_text}}, topic_count, page_reference_count, cross_reference_count and index_stories[] {story_id, frame_ids, page_ids, page_names, paragraph_count, length, overset} – generated indexes in the document. topic_contains filters by any level (case-insensitive; sub-topics of a match are only listed if they match too); include_references false leaves out the reference lists. Read-only.

generate_indexGenerate or update the index

Generate the index (Register) from the entries of add_index_entry into a new text frame on page_id – at position_mm or exactly at bounds_mm; autoflow true lets InDesign add frames and pages until it fits (pages_added). replace true updates the existing index in its frame. Options (InDesign keeps them in the document for the next run): title ("" for none), title_style, format nested (default) | run_in, include_section_headings (letters A–Z), include_empty_sections, include_hidden_layers, level_styles[] (paragraph styles for levels 1–4), section_heading_style, page_number_style, cross_reference_style, cross_reference_topic_style, separators {following_topic, between_entries, page_range, between_page_numbers, before_cross_reference, entry_end} (metacharacters allowed, e.g. "^=" en dash). Without level styles InDesign creates its own index paragraph styles (localized names). Returns story_id, frame_id, frame_ids, page_id, page_name, page_ids, page_names, bounds_mm (of the first frame, relative to its page), paragraph_count, length, overset, replaced and lines[] {text, paragraph_style} (first 500 paragraphs; lines_truncated). Plus pages_added. Text placed with place_text_file brings no index from Word – build it with add_index_entry.

check_print_on_demandCheck a book for print-on-demandnur lesend

Check the interior of a book (Innenteil) against the limits of a print-on-demand service before upload. Read-only. Each limit comes from the call or, when omitted, from the server configuration (print_on_demand); a check without a limit is reported as skipped – take the values from the printer's current specification. Checks[] {check, status pass|fail|skipped, required, actual, findings[]}: page_count (min_page_count, max_page_count, page_count_multiple); inside_margin (the inside margin, Bundsteg, of every page against the tier for the page count: inside_margin_tiers [{max_pages, min_mm}], the first tier whose max_pages is not below the page count); outside_margins (outside, top and bottom margin of every page against min_outside_margin_mm); bleed (on facing pages the inside bleed must be 0 – InDesign keeps it as left/inside –, top, bottom and outside equal bleed_mm within bleed_tolerance_mm (default 0.1), and objects reaching beyond the trim need bleed at all); objects_in_margin (objects that do not bleed but come closer to the trim than the minimum margins); objects_across_spine (facing pages: objects reaching over the spine into the facing page – cut off there when the inside bleed is 0); min_font_size (every text run, also on parent pages and in overset text, against min_font_size_pt); image_resolution (effective ppi of placed pixel images against min_ppi; placed PDF/EPS are skipped); fonts (every document font installed and allowed for PDF embedding – whether the fonts are really embedded only the exported PDF shows). Returns passed (no check failed), failed_checks[], skipped_checks[], page_count, facing_pages, page_size_mm, checks[], findings_total and findings_truncated (max_findings, default 200, over all checks). Export for upload with export_pdf and use_document_bleed true.

create_book_coverCreate a book cover document

Create a new document for the one-piece cover of a paperback (Umschlag: back cover, spine, front cover side by side) from the page_count of the interior, its trim size (trim_width_mm, trim_height_mm, Endformat) and the paper thickness per page as the printer states it (spine_per_page_mm or spine_per_page_in; the inch value wins when both are set): spine width = page_count × thickness, page width = 2 × trim width + spine, height = trim height. bleed_mm becomes the document bleed on all four sides (export with export_pdf and use_document_bleed true; the PDF then measures page size plus twice the bleed). safety_margin_mm sets the margins (Satzspiegel guides) on all sides. Vertical guides mark both spine folds; spine_safety_mm adds two guides inside the spine for spine text. barcode_area {width_mm, height_mm, offset_x_mm (from the spine fold), offset_y_mm (from the bottom trim)} reserves the space for the barcode on the back cover as a non-printing empty frame named barcode_area. Every value can come from the call or the server configuration (print_on_demand); take them from the printer's current specification. The new document is unsaved (save_document with path). Returns document_id, name, page_id, page_count, spine_width_mm, spine_width_in, trim_size and size_with_bleed {width/height in mm, pt and in}, bleed_mm, safety_margin_mm, back_cover_mm, spine_mm, front_cover_mm {x, width}, guides[] {guide_id, role, position_mm}, barcode_frame_id and barcode_area_mm.

export_epubExport as EPUB

Export the document as an e-book (EPUB) to path (a .epub file; an existing file only with overwrite true, otherwise io_error with details.code file_exists). layout is required: reflowable (text reflows to the reader's screen and font size; for text-led books) or fixed_layout (every page keeps its layout; for picture books, comics, heavily designed pages). Options apply to this call only and are restored afterwards: epub_version 2 or 3 (reflowable; fixed layout is always EPUB 3), cover none | first_page | image (with cover_image_path, a JPEG, PNG or GIF that must exist), toc_style (an existing TOC style, see list_toc_styles and define_toc_style – it builds the EPUB navigation; without it the navigation lists only file names), image_resolution 72 | 96 | 150 | 300 ppi, image_format automatic | jpeg | png | gif, jpeg_quality low | medium | high | maximum; reflowable only: export_order layout | articles | xml, split_by_paragraph_style (start a new file at each paragraph of this style, e.g. chapter headings), embed_fonts; fixed layout only: page_range (printed page names like export_pdf), spread_control document | physical | synthetic | none, orientation portrait | landscape | auto (InDesign itself writes landscape even for upright pages, which locks reading apps to landscape; the server therefore sets the orientation in the finished file – by default from the page format – and returns orientation_set {value, previous, changed}). metadata {title, creator, publisher, description, subject, rights, date, identifier} goes into the package (an identifier such as urn:isbn:… is added next to InDesign's own unique id); the EPUB language comes from the document's default language (text defaults), not from a parameter. Returns path, bytes, overwritten, layout, settings_used (the values InDesign exported with), document_language, settings_changed_for_export and document_marked_modified – InDesign marks the document as modified whenever an export setting is set, although the settings are restored; close without saving if nothing else changed. warnings[] name missing title or creator, a missing default language, no TOC style, no cover, objects not anchored in the text flow (reflowable) and fonts that cannot be embedded. Check the document before with check_epub and the file after with check_epub path; for print use export_pdf, for page images export_page_image. Can take minutes on a long book.

check_epubCheck a book for EPUBnur lesend

Check an e-book before and after export_epub. Read-only. Without path it checks the document in InDesign for the given layout (reflowable, default, or fixed_layout): document_language (an EPUB needs dc:language – error when the text defaults have no language), toc_style (error when the named toc_style does not exist; warning when no TOC style is set for the EPUB), metadata (warning without title or creator in the EPUB settings), and for reflowable unanchored_objects (graphics and groups on pages that are not anchored in the text flow – their place in the EPUB follows the export order; anchor_frame_in_text), parent_page_objects (content on parent pages, left out of a reflowable EPUB – fine for running heads and page numbers) and paragraph_styles (stories with basic paragraph styles), image_resolution against min_ppi (from the call or the server configuration epub.min_ppi; skipped without a limit) and fonts (not installed – an error for fixed layout, which needs embedded fonts). With path it checks the finished .epub file without InDesign: zip_structure (mimetype first and uncompressed), container (META-INF/container.xml and the package document), opf_metadata (version, dc:title, dc:language, dc:identifier matching unique-identifier; warning without dc:creator), manifest_files (every manifest file present, spine entries in the manifest), navigation (EPUB 3 nav with a toc, EPUB 2 NCX), references (src and href in the content files point to files in the archive) and cover (warning without a cover image). Returns passed (no error), checked document | file, checks_run[], errors, findings[] {check, severity error | warning, page_id, page_name, object_id or file, hint}, findings_total and findings_truncated (max_findings, default 200); with path also epub_version, layout, title, language, creators[], identifiers[], file_count, nav_document, nav_entries, ncx, cover_image, fonts[] and fonts_obfuscated. It does not replace EPUBCheck or the e-book shop's own preview tool.

preflight_documentRun InDesign® preflightnur lesend

Run InDesign's preflight (Preflight) with profile_name or, without it, the document's working profile (falls back to the first available profile when the working profile is invalid). Waits for the process, returns profile_used, summary ("None" when there are no errors), error_count and findings[] with category, description, page_name and item, capped by max_findings (1–500, default 100). With list_profiles_only true only profiles[] is returned. Read-only: the process is created, awaited and removed. Caveat: overset text (Übersatz) is not always reported with the right page – get_frame_text on the last frame of each story is the reliable check.

check_typographyCheck typography rules (read-only)nur lesend

Find violations of general typesetting rules and report them – never change anything. The rule catalogue is a data table in the package (rules/typography-rules.json): character rules run as InDesign GREP searches (double_space, space_before_punct, straight_quotes, apostrophe, hyphen_as_dash, dash_spacing, three_dots, number_unit_space, number_unit_missing_space, abbreviation_space, thousands_grouping, empty_paragraph, double_paragraph_break, tab_as_indent, trailing_space); line rules run on the composed lines of every text frame like get_frame_lines (widow – Hurenkind, error; orphan – Schusterjunge, warning; heading_at_column_end; single_word_last_line; hyphen_ladder with max_consecutive_hyphens, default 3; empty_line_at_column_start; column_first_baselines_differ, more than 0.1 mm). locale de (default), de-CH (guillemets) or en (curly quotes, closed em dash, no space before %). scope document (default), frame or story (both need frame_id). page_range limits the check to pages by printed page name like export_pdf ("6-8", "1, 3-5", "+3"): line rules read only frames on those pages, character findings elsewhere are left out (returned as page_range_used, "all" without it). Line rules read every line and take far longer than the character rules – on a long book check part of it per call with page_range; above 100 text frames in scope document without page_range a warning says so. rules[] limits to those ids, exclude_rules[] drops some; unknown ids are invalid_argument. Returns findings[] {rule_id, severity, category, message, story_id, frame_id, page_id, page_name, start_index, end_index (story indices for the *_to_range tools), snippet, suggestion (often a find_replace GREP pattern)}, counts per rule_id, rules_checked[], rules_failed[] (a GREP pattern InDesign rejected – warning, the rest runs), frames_checked, findings_dropped and truncated (max_findings caps only findings[]; every rule still runs and counts stays complete). Sources: Forssman/de Jong (Detailtypografie), Duden (Satz und Korrektur), DIN 5008, Bier (typokurz), Bringhurst (locale en). Not checked: spelling, grammar, content, text inside placed graphics; table cells are skipped in this version (warning tables_skipped). Read-only.