Skip to content

hardis:doc:project2markdown

Description

Generates a markdown documentation from a SFDX project

  • Objects
  • Flows
  • Apex
  • Lightning Pages
  • SFDX-Hardis Config
  • Branches & Orgs
  • Installed Packages
  • Manifests

Can work on any sfdx project, no need for it to be a sfdx-hardis flavored one.

Generates markdown files will be written in docs folder (except README.md where a link to doc index is added)

  • You can customize the pages following mkdocs-material setup documentation
  • You can manually add new markdown files in the "docs" folder to extend this documentation and add references to them in "mkdocs.yml"
  • You can also add images in folder "docs/assets" and embed them in markdown files.

To read Flow documentations if your markdown reader doesn't handle MermaidJS syntax, this command could require @mermaid-js/mermaid-cli

  • Run npm install @mermaid-js/mermaid-cli --global if puppeteer works in your environment
  • It can also be run as a docker image

Both modes will be tried by default, but you can also force one of them by defining environment variable MERMAID_MODES=docker or MERMAID_MODES=cli

sfdx-hardis docker image is alpine-based and does not succeed to run mermaid/puppeteer: if you can help, please submit a PR !

If Flow history doc always display a single state, you probably need to update your workflow configuration:

Screenshot flow doc

Screenshot project documentation

Screenshot project documentation

Screenshot project documentation

If it is a sfdx-hardis CI/CD project, a diagram of the branches and orgs strategy will be generated.

If AI integration is configured, documentation will contain a summary of the Flow.

If you have a complex strategy, you might need to input property mergeTargets in branch-scoped sfdx-hardis.yml file to have a correct diagram.

Doc HTML Pages

To read the documentation as HTML pages, run the following code (you need Python on your computer)

pip install mkdocs-material mkdocs-exclude-search mdx_truly_sane_lists || python -m pip install mkdocs-material mkdocs-exclude-search mdx_truly_sane_lists || py -m pip install mkdocs-material mkdocs-exclude-search mdx_truly_sane_lists
mkdocs serve -v || python -m mkdocs serve -v || py -m mkdocs serve -v

To just generate HTML pages that you can host anywhere, run mkdocs build -v || python -m mkdocs build -v || py -m mkdocs build -v

Parameters

Name Type Description Default Required Options
debug
-d		 boolean Activate debug mode (more logs)
diff-only boolean Generate documentation only for changed files (used for monitoring)
flags-dir option undefined
json boolean Format output as json.
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
with-history boolean Generate a markdown file with the history diff of the Flow

Examples

$ sf hardis:doc:project2markdown

$ sf hardis:doc:project2markdown --with-history