Skip to main content

DOCX Formatting Issues

aprity can generate documentation in DOCX (Microsoft Word) format. If the generated document has formatting problems, broken layouts, or missing content, this guide covers the most common causes and solutions.

info

DOCX export is available on Enterprise plans. If you do not see the DOCX download option, verify your plan includes this feature.

Common causes​

Custom template incompatible​

If you are using a custom DOCX template, formatting issues are most often caused by template structure that does not meet the aprity template specification.

Symptoms:

  • Content appears in the wrong locations.
  • Headers, footers, or cover page elements are missing or duplicated.
  • Styles (fonts, colors, spacing) do not apply correctly.

Solution:

  • Switch to the system template to confirm the issue is template-related. In the aprity app, select the default template when starting a scan or generating documentation.
  • Review the Custom DOCX Templates guide for template requirements.
  • Ensure your custom template uses the placeholder styles and content controls specified in the template documentation.
tip

When building a custom template, start from the aprity system template and modify it rather than building from scratch. This ensures all required structural elements are present.

Special characters in metadata names​

Salesforce object names, field labels, or automation names that contain special characters (accented letters, non-Latin scripts, symbols) can occasionally cause rendering issues in the DOCX output.

Symptoms:

  • Specific object or field names display as garbled text or question marks.
  • Table of contents entries are corrupted for certain objects.

Solution:

  • This is uncommon but can occur with certain character combinations. If you encounter this, contact support@aprity.ai with the specific object or field name that is affected.
  • As a workaround, you can download the documentation in HTML or Markdown format, which handle special characters more reliably.

Large document exceeding Word limits​

Microsoft Word has practical limits on document size and complexity. For very large Salesforce orgs, the generated DOCX may become unwieldy.

Symptoms:

  • Word takes a long time to open the document or becomes unresponsive.
  • Images or diagrams fail to render.
  • The document file size exceeds 50 MB.

Solution:

  • Use scoped scans to split documentation into smaller, more manageable documents. For example, scan related groups of objects separately rather than the entire org in one scan.
  • For very large orgs, consider using HTML format for the full documentation and DOCX for specific object groups that need to be shared as Word documents.

Table of contents not populated​

The generated DOCX includes a table of contents that needs to be refreshed when the document is first opened.

Symptoms:

  • The table of contents shows "Error! Bookmark not defined" or is empty.

Solution:

  • After opening the document in Word, right-click the table of contents and select Update Field > Update entire table.
  • This is standard Word behavior for documents with generated tables of contents.

Verifying the output​

To confirm whether an issue is specific to DOCX formatting:

  1. Download the same scan results in HTML or Markdown format.
  2. Compare the content. If the content is correct in other formats but broken in DOCX, the issue is format-specific.
  3. If content is missing across all formats, see Empty or Incomplete Documentation.

Still not working?​

If formatting issues persist:

  1. Note which sections or objects are affected.
  2. Specify whether you are using the system template or a custom template.
  3. Contact support at support@aprity.ai with the scan ID and a screenshot of the formatting issue.