How to Deliver Archify Diagrams with a Specific Output Path

You can deliver Archify diagrams to a custom location by using the --output flag in the CLI or by passing a path argument to helper scripts like scripts/build-start.mjs and scripts/build-guide.mjs.

Archify, an open-source diagramming tool from the tt-a1i/archify repository, provides flexible options for controlling where generated files land. Whether you are integrating diagrams into a documentation pipeline or organizing outputs into structured directories, understanding the output path resolution is essential for reproducible builds.

Using the CLI --output Flag

The primary interface for specifying a destination is the archify render command. This command accepts a --output (or -o) parameter that overrides the default behavior of placing files beside the source.

The syntax follows this pattern:

archify render <type> <input-file> --output <target-path>

• <type> — The diagram format, such as workflow, architecture, or mermaid.
• <input-file> — The source file in JSON, YAML, or Mermaid format.
• <target-path> — An absolute or relative path where the final HTML (or other supported format) will be written.

If you omit the --output flag, Archify defaults to creating the output file next to the source with a .html extension.

Example: Rendering to a Custom Directory

# Render a workflow diagram to the docs folder

archify render workflow examples/workflow.json \
    --output ./docs/diagrams/workflow.html

Working with Build Scripts

For specialized generation tasks, the repository includes convenience scripts that accept output paths as positional arguments. These scripts wrap the core rendering logic while ensuring static assets are co-located with the generated HTML via the copySiteAssets function.

Build Start Script

The scripts/build-start.mjs script generates the Start page and accepts an optional output path:

node scripts/build-start.mjs ./public/start-page.html

Build Guide Script

Similarly, scripts/build-guide.mjs handles the Guide page generation:

node scripts/build-guide.mjs ./public/guide.html

Both utilities internally resolve paths and create necessary directories before writing files.

Understanding the Output Path Resolution

Behind the scenes, Archify centralizes path logic in archify/renderers/shared/output-path.mjs. This module handles directory creation, path normalization, and safety checks to ensure reliable file delivery regardless of whether you are running an installed skill or a local development build.

The output-path.mjs Helper

The output-path.mjs module exposes utilities that resolve the final file name and ensure parent directories exist before writing. This prevents errors when targeting nested output locations that have not yet been created.

The test suite in archify/test/output-path.test.mjs validates these behaviors, confirming that the module correctly handles:

• Relative path resolution from the current working directory.
• Absolute path preservation.
• Directory creation for missing parent folders.

Step-by-Step Workflow Example

Follow this pattern to deliver diagrams with precise control over their destination:

1. Prepare your source file (e.g., my-workflow.json describing your diagram).

2. Run the render command with an explicit output location:

   archify render workflow my-workflow.json --output ./output/diagram.html

3. Verify asset co-location — The generated HTML appears at the specified path, and copySiteAssets ensures static dependencies reside alongside it.

Summary

• Use the --output flag with archify render to specify a custom destination for any diagram type.
• Leverage scripts/build-start.mjs and scripts/build-guide.mjs for page-specific generation with positional path arguments.
• The output-path.mjs module in archify/renderers/shared/ handles directory creation and path normalization automatically.
• When omitted, outputs default to the source file's directory with a .html extension.

Frequently Asked Questions

How do I specify a custom output directory for Archify diagrams?

Use the --output flag followed by your desired path. For example: archify render workflow input.json --output ./docs/output.html. The output-path.mjs helper will create the directory structure if it does not exist.

What happens if I don't provide an output path?

Archify writes the generated file beside the source file using the same base name but with a .html extension. This default behavior ensures you can quickly generate previews without specifying additional parameters.

Can I use relative paths for the output?

Yes. The output-path.mjs module resolves relative paths against the current working directory. Both relative paths like ./docs/diagram.html and absolute paths like /home/user/project/docs/diagram.html are supported.

How are static assets handled when using a custom output path?

Helper scripts such as build-start.mjs and build-guide.mjs invoke copySiteAssets to ensure that CSS, JavaScript, and other static dependencies are copied to the same directory as the generated HTML, maintaining proper relative links regardless of the output location.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}