|
| 1 | +--- |
| 2 | +id: docify |
| 3 | +title: Docify |
| 4 | +sidebar_position: 8 |
| 5 | +--- |
| 6 | + |
| 7 | +# Docify |
| 8 | + |
| 9 | +The `docify` command transforms a CALM architecture JSON file into human-readable documentation. It supports two primary output modes: |
| 10 | + |
| 11 | +- **Website generation** — uses the built-in template bundle to produce a fully structured Markdown documentation site ready to publish with a static site generator. |
| 12 | +- **Custom Markdown reports** — uses your own Handlebars (`.hbs`) or Markdown (`.md`) templates to render bespoke reports, conformance summaries, runbooks, or any other document format you need. |
| 13 | + |
| 14 | +In both modes, `docify` processes your architecture model through a set of templates and writes the resulting files to an output directory. Template rendering is powered by [CALM Widgets](../core-concepts/widgets) — a Handlebars-based component system that provides built-in helpers for tables, lists, Mermaid diagrams, and more. You can use these widgets directly inside your own templates to produce rich, structured output from your architecture data. |
| 15 | + |
| 16 | +## Basic Usage |
| 17 | + |
| 18 | +### Generate a documentation website |
| 19 | + |
| 20 | +To generate a documentation website using the built-in template bundle, provide the path to your architecture file and the directory where the output should be written: |
| 21 | + |
| 22 | +```shell |
| 23 | +calm docify -a architecture.json -o docs/output |
| 24 | +``` |
| 25 | + |
| 26 | +This uses the default website template bundle and produces a fully structured Markdown documentation site in `docs/output`. |
| 27 | + |
| 28 | +### Generate a custom Markdown report |
| 29 | + |
| 30 | +To produce a tailored document — such as a compliance report or runbook — supply your own template: |
| 31 | + |
| 32 | +```shell |
| 33 | +calm docify -a architecture.json -o reports/ -t my-report-template.hbs |
| 34 | +``` |
| 35 | + |
| 36 | +Or point to a directory of templates to generate multiple output files in one pass: |
| 37 | + |
| 38 | +```shell |
| 39 | +calm docify -a architecture.json -o reports/ -d my-templates/ |
| 40 | +``` |
| 41 | + |
| 42 | +## Command Options |
| 43 | + |
| 44 | +- **`-a, --architecture <file>`**: _(required)_ Path to the CALM architecture JSON file. |
| 45 | +- **`-o, --output <file>`**: _(required)_ Path to the output directory where the generated documentation will be written. |
| 46 | +- **`--clear-output-directory`**: Clear the output directory before processing (default: false). |
| 47 | +- **`-t, --template <path>`**: Path to a single `.hbs` or `.md` template file to use instead of the built-in bundle. |
| 48 | +- **`-d, --template-dir <path>`**: Path to a directory of `.hbs`/`.md` templates to use instead of the built-in bundle. |
| 49 | +- **`-u, --url-to-local-file-mapping <path>`**: Path to a JSON file that maps URLs to local file paths (see [URL Mapping](#url-to-local-file-mapping) below). |
| 50 | +- **`--scaffold`**: Copy the built-in template files into the output directory without processing them. Use this to obtain a starting point for customisation or for live-reload workflows. |
| 51 | +- **`-v, --verbose`**: Enable verbose logging. |
| 52 | + |
| 53 | +Only one of `--template` or `--template-dir` may be specified. If neither is provided, the built-in website bundle is used. |
| 54 | + |
| 55 | +## Examples |
| 56 | + |
| 57 | +### Generate a documentation website with the built-in bundle |
| 58 | + |
| 59 | +```shell |
| 60 | +calm docify -a my-architecture.json -o docs/output |
| 61 | +``` |
| 62 | + |
| 63 | +Processes `my-architecture.json` using the default template bundle and writes a ready-to-publish documentation site to `docs/output`. |
| 64 | + |
| 65 | +### Generate a custom Markdown report from a single template |
| 66 | + |
| 67 | +```shell |
| 68 | +calm docify -a my-architecture.json -o reports/ -t templates/compliance-report.hbs |
| 69 | +``` |
| 70 | + |
| 71 | +Renders the architecture against a single Handlebars template, producing a focused report (e.g. a compliance summary or runbook) in `reports/`. |
| 72 | + |
| 73 | +### Generate multiple documents from a template directory |
| 74 | + |
| 75 | +```shell |
| 76 | +calm docify -a my-architecture.json -o reports/ -d my-templates/ |
| 77 | +``` |
| 78 | + |
| 79 | +Every `.hbs` and `.md` file found in `my-templates/` is rendered against the architecture and the results are written to `reports/`. This is useful when you need several different views of the same architecture — for example, a technical overview, a controls checklist, and a deployment guide — all generated in one command. |
| 80 | + |
| 81 | +### Scaffold the built-in templates for customisation |
| 82 | + |
| 83 | +```shell |
| 84 | +calm docify -a my-architecture.json -o docs/output --scaffold |
| 85 | +``` |
| 86 | + |
| 87 | +The built-in template files are copied to `docs/output` without being processed. You can then edit them and re-run `docify` with `-d docs/output` to render your customised templates. |
| 88 | + |
| 89 | +### Clear the output directory before regenerating |
| 90 | + |
| 91 | +```shell |
| 92 | +calm docify -a my-architecture.json -o docs/output --clear-output-directory |
| 93 | +``` |
| 94 | + |
| 95 | +Removes all existing files from `docs/output` before writing the new documentation, ensuring no stale files remain. |
| 96 | + |
| 97 | +## URL to Local File Mapping |
| 98 | + |
| 99 | +When your architecture references schemas or patterns via canonical URLs (e.g., `https://example.com/standards/node-standard.json`) but the actual files exist on your local filesystem, the `-u, --url-to-local-file-mapping` option lets you redirect those URLs to local paths. |
| 100 | + |
| 101 | +### Mapping File Format |
| 102 | + |
| 103 | +Create a JSON file that maps URLs to relative file paths: |
| 104 | + |
| 105 | +```json |
| 106 | +{ |
| 107 | + "https://example.com/standards/node-standard.json": "standards/node-standard.json", |
| 108 | + "https://example.com/standards/relationship-standard.json": "standards/relationship-standard.json" |
| 109 | +} |
| 110 | +``` |
| 111 | + |
| 112 | +Paths are resolved relative to the mapping file's location. |
| 113 | + |
| 114 | +### Example Usage |
| 115 | + |
| 116 | +```shell |
| 117 | +calm docify -a architecture.json -o docs/output -u url-mapping.json |
| 118 | +``` |
0 commit comments