Skip to content

hardis:doc:packagexml2markdown

Description

Command Behavior

Generates a Markdown documentation file from a Salesforce package.xml file.

This command provides a convenient way to visualize and document the metadata components defined within a package.xml file. It's particularly useful for:

  • Understanding Project Scope: Quickly grasp what metadata types and components are included in a specific deployment or retrieval.
  • Documentation: Create human-readable documentation of your project's metadata structure.
  • Collaboration: Share a clear overview of metadata changes with team members or stakeholders.

Key features:

  • Flexible Input: You can specify the path to a package.xml file using the --inputfile flag. If not provided, the command will automatically look for package.xml files in the manifest folder.
  • Customizable Output: You can force the path and name of the output Markdown file using the --outputfile flag.
  • VS Code Integration: Automatically opens the generated Markdown file in a new VS Code tab for immediate review.
Technical explanations

The command's technical implementation involves:

  • XML Parsing: It reads the content of the specified package.xml file and parses its XML structure to extract the metadata types and their members.
  • Markdown Generation: It utilizes the DocBuilderPackageXML.generatePackageXmlMarkdown utility to transform the parsed package.xml data into a structured Markdown format. This utility handles the formatting and organization of the metadata information.
  • File System Operations: It uses fs-extra (implicitly through DocBuilderPackageXML) to read the input package.xml and write the generated Markdown file.
  • WebSocket Communication: It interacts with a WebSocket client (WebSocketClient.requestOpenFile) to open the generated Markdown file in a VS Code tab, enhancing user experience.
  • Salesforce Org Context: It can optionally use the target-org flag to provide context, such as the instance URL, which might be used for generating links or additional information within the Markdown.

Agent Mode

Supports non-interactive execution with --agent:

sf hardis:doc:packagexml2markdown --agent

In agent mode, all interactive prompts are skipped and default values are used.

Parameters

Name Type Description Default Required Options
agent boolean Run in non-interactive mode for agents and automation
debug
-d		 boolean Activate debug mode (more logs)
flags-dir option undefined
inputfile
-x		 option Path to package.xml file. If not specified, the command will look in manifest folder
json boolean Format output as json.
outputfile
-f		 option Force the path and name of output report file. Must end with .md
skipauth boolean Skip authentication check when a default username is required
target-org
-o		 option undefined
websocket option Websocket host:port for VsCode SFDX Hardis UI integration

Examples

$ sf hardis:doc:packagexml2markdown

$ sf hardis:doc:packagexml2markdown --agent

$ sf hardis:doc:packagexml2markdown --inputfile manifest/package-all.xml