Skip to main content

Markdown Output

The Markdown format produces a set of .md files organized by Salesforce object. It is the most portable format aprity offers and is available on all plans.

File Structure​

When you download the Markdown output, you receive a .zip archive containing:

documentation/
  index.md                  # Top-level index with links to all objects
  Account/
    Account.md              # Full documentation for the Account object
  Contact/
    Contact.md
  Opportunity/
    Opportunity.md
  ...
  processes/
    process-index.md        # Cross-object process index
    Process_Name.md         # Individual process documentation
  rules/
    rule-index.md           # Business rule index

Each object file is self-contained and can be read independently.

Content Sections​

Every object Markdown file includes the following sections:

Overview​

A summary of the object's purpose, including its business label and a plain-language description generated by AI analysis.

Business Rules​

A numbered list of functional rules extracted from triggers, flows, validation rules, and process builders. Each rule includes:

  • Rule name -- the business-friendly label assigned by aprity.
  • Type -- the automation type (Trigger, Flow, Validation Rule, etc.).
  • Description -- a plain-language explanation of what the rule does.
  • Evidence -- the specific metadata elements that support the rule.

Dependencies​

A list of objects and components that this object references or is referenced by, organized as incoming and outgoing dependencies.

Technical Details​

Field-level metadata, record types, page layouts, and other structural information about the object.

Evidence Sections​

Each business rule includes an evidence block that traces the rule back to its source metadata. In Markdown, evidence is rendered as a collapsible details block:

<details>
<summary>Evidence</summary>

- Source: `Account_Trigger` (Apex Trigger)
- Fields: `Account.Industry`, `Account.AnnualRevenue`
- Condition: When Industry equals "Technology" and AnnualRevenue > 1000000

</details>

This keeps the document readable at a glance while preserving traceability for auditors and technical reviewers.

tip

Collapsible details blocks render natively on GitHub, GitLab, and most Markdown viewers. If your wiki does not support <details>, the content still displays as regular text.

Git-Friendly Design​

The Markdown output is designed for version control workflows:

  • One file per object -- changes to a single object produce a diff in only one file.
  • Deterministic ordering -- sections and rules are sorted consistently across scans, minimizing spurious diffs.
  • Plain text -- no binary content. Every change is visible in a standard git diff.

This makes it practical to commit aprity documentation alongside your source code and track how your Salesforce org evolves over time.

info

Consider setting up a scheduled scan that commits Markdown output to a Git repository on a weekly or monthly basis. This creates an automatic audit trail of your org's documentation history.

Limitations​

  • No interactive navigation or search -- Markdown files are static text.
  • Images and diagrams are not included -- the Markdown format focuses on textual documentation.
  • Styling depends on the viewer -- rendering varies between GitHub, VS Code, Notion imports, and other Markdown tools.

When to Use Markdown​

  • You want to store documentation alongside code in a Git repository.
  • Your team reviews documentation through pull requests.
  • You need a lightweight, portable format that works everywhere.
  • You plan to import documentation into a wiki or knowledge base that accepts Markdown.